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

Pull documentation updates from Jonathan Corbet:
 "It's a somewhat calmer cycle for docs this time, as the churn of the
  mass RST conversion is happily mostly behind us.

   - A new document on reproducible builds.

   - We finally got around to zapping the documentation for hardware
     support that was removed in 2004; one doesn't want to rush these
     things.

   - The usual assortment of fixes, typo corrections, etc"

* tag 'docs-5.4' of git://git.lwn.net/linux: (67 commits)
  Documentation: kbuild: Add document about reproducible builds
  docs: printk-formats: Stop encouraging use of unnecessary %h[xudi] and %hh[xudi]
  Documentation: Add "earlycon=sbi" to the admin guide
  doc:lock: remove reference to clever use of read-write lock
  devices.txt: improve entry for comedi (char major 98)
  docs: mtd: Update spi nor reference driver
  doc: arm64: fix grammar dtb placed in no attributes region
  Documentation: sysrq: don't recommend 'S' 'U' before 'B'
  mailmap: Update email address for Quentin Perret
  docs: ftrace: clarify when tracing is disabled by the trace file
  docs: process: fix broken link
  Documentation/arm/samsung-s3c24xx: Remove stray U+FEFF character to fix title
  Documentation/arm/sa1100/assabet: Fix 'make assabet_defconfig' command
  Documentation/arm/sa1100: Remove some obsolete documentation
  docs/zh_CN: update Chinese howto.rst for latexdocs making
  Documentation: virt: Fix broken reference to virt tree's index
  docs: Fix typo on pull requests guide
  kernel-doc: Allow anonymous enum
  Documentation: sphinx: Don't parse socket() as identifier reference
  Documentation: sphinx: Add missing comma to list of strings
  ...

249 files changed, 5169 insertions, 3963 deletions

diff --git a/.mailmap b/.mailmap
index 1ad4fd655619..62bf76cb9972 100644
--- a/.mailmap
+++ b/.mailmap
@@ -47,6 +47,8 @@ Boris Brezillon <bbrezillon@kernel.org> <b.brezillon.dev@gmail.com>
 Boris Brezillon <bbrezillon@kernel.org> <b.brezillon@overkiz.com>
 Brian Avery <b.avery@hp.com>
 Brian King <brking@us.ibm.com>
+Chao Yu <chao@kernel.org> <chao2.yu@samsung.com>
+Chao Yu <chao@kernel.org> <yuchao0@huawei.com>
 Christoph Hellwig <hch@lst.de>
 Christophe Ricard <christophe.ricard@gmail.com>
 Corey Minyard <minyard@acm.org>
@@ -80,6 +82,8 @@ Frank Rowand <frowand.list@gmail.com> <frowand@mvista.com>
 Frank Rowand <frowand.list@gmail.com> <frank.rowand@am.sony.com>
 Frank Rowand <frowand.list@gmail.com> <frank.rowand@sonymobile.com>
 Frank Zago <fzago@systemfabricworks.com>
+Gao Xiang <xiang@kernel.org> <gaoxiang25@huawei.com>
+Gao Xiang <xiang@kernel.org> <hsiangkao@aol.com>
 Greg Kroah-Hartman <greg@echidna.(none)>
 Greg Kroah-Hartman <gregkh@suse.de>
 Greg Kroah-Hartman <greg@kroah.com>
@@ -90,6 +94,9 @@ Henrik Kretzschmar <henne@nachtwindheim.de>
 Henrik Rydberg <rydberg@bitmath.org>
 Herbert Xu <herbert@gondor.apana.org.au>
 Jacob Shin <Jacob.Shin@amd.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@google.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@motorola.com>
+Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk.kim@samsung.com>
 James Bottomley <jejb@mulgrave.(none)>
 James Bottomley <jejb@titanic.il.steeleye.com>
 James E Wilson <wilson@specifix.com>
@@ -181,6 +188,11 @@ Nguyen Anh Quynh <aquynh@gmail.com>
 Nicolas Ferre <nicolas.ferre@microchip.com> <nicolas.ferre@atmel.com>
 Nicolas Pitre <nico@fluxnic.net> <nicolas.pitre@linaro.org>
 Nicolas Pitre <nico@fluxnic.net> <nico@linaro.org>
+Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
+Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
+Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
+Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
 Paolo 'Blaisorblade' Giarrusso <blaisorblade@yahoo.it>
 Patrick Mochel <mochel@digitalimplant.org>
 Paul Burton <paul.burton@mips.com> <paul.burton@imgtec.com>
@@ -191,11 +203,7 @@ Pratyush Anand <pratyush.anand@gmail.com> <pratyush.anand@st.com>
 Praveen BP <praveenbp@ti.com>
 Punit Agrawal <punitagrawal@gmail.com> <punit.agrawal@arm.com>
 Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com>
-Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
-Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
-Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
-Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
+Quentin Perret <qperret@qperret.net> <quentin.perret@arm.com>
 Rajesh Shah <rajesh.shah@intel.com>
 Ralf Baechle <ralf@linux-mips.org>
 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
@@ -230,6 +238,7 @@ Sumit Semwal <sumit.semwal@ti.com>
 Tejun Heo <htejun@gmail.com>
 Thomas Graf <tgraf@suug.ch>
 Thomas Pedersen <twp@codeaurora.org>
+Todor Tomov <todor.too@gmail.com> <todor.tomov@linaro.org>
 Tony Luck <tony.luck@intel.com>
 TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
 TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description:	Bus scanning interval, microseconds component.
                 control systems are attached/generate presence for as short as
                 100 ms - hence the tens-to-hundreds milliseconds scan intervals
                 are required.
-                see Documentation/w1/w1.generic for detailed information.
+                see Documentation/w1/w1-generic.rst for detailed information.
 Users:          any user space application which wants to know bus scanning
                 interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What:		/sys/bus/w1/devices/.../pio
 Date:           May 2012
 Contact:        Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:    read/write the contents of the two PIO's of the DS28E04-100
-                see Documentation/w1/slaves/w1_ds28e04 for detailed information
+                see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:          any user space application which wants to communicate with DS28E04-100
 
 
@@ -11,5 +11,5 @@ What:		/sys/bus/w1/devices/.../eeprom
 Date:           May 2012
 Contact:        Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:    read/write the contents of the EEPROM memory of the DS28E04-100
-                see Documentation/w1/slaves/w1_ds28e04 for detailed information
+                see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:          any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What:		/sys/bus/w1/devices/.../w1_seq
 Date:           Apr 2015
 Contact:        Matt Campbell <mattrcampbell@gmail.com>
 Description:    Support for the DS28EA00 chain sequence function
-                see Documentation/w1/slaves/w1_therm for detailed information
+                see Documentation/w1/slaves/w1_therm.rst for detailed information
 Users:          any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
new file mode 100644
index 000000000000..18c2865bd322
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -0,0 +1,98 @@
+===================================
+cfag12864b LCD Driver Documentation
+===================================
+
+:License:               GPLv2
+:Author & Maintainer:   Miguel Ojeda Sandonis
+:Date:                  2006-10-27
+
+
+
+.. INDEX
+
+        1. DRIVER INFORMATION
+        2. DEVICE INFORMATION
+        3. WIRING
+        4. USERSPACE PROGRAMMING
+
+1. Driver Information
+---------------------
+
+This driver supports a cfag12864b LCD.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer:  Crystalfontz
+:Device Name:   Crystalfontz 12864b LCD Series
+:Device Code:   cfag12864b
+:Webpage:       http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type:          LCD (Liquid Crystal Display)
+:Width:         128
+:Height:        64
+:Colors:        2 (B/N)
+:Controller:    ks0108
+:Controllers:   2
+:Pages:         8 each controller
+:Addresses:     64 each page
+:Data size:     1 byte each address
+:Memory size:   2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+
+
+3. Wiring
+---------
+
+The cfag12864b LCD Series don't have official wiring.
+
+The common wiring is done to the parallel port as shown::
+
+  Parallel Port                          cfag12864b
+
+    Name Pin#                            Pin# Name
+
+  Strobe ( 1)------------------------------(17) Enable
+  Data 0 ( 2)------------------------------( 4) Data 0
+  Data 1 ( 3)------------------------------( 5) Data 1
+  Data 2 ( 4)------------------------------( 6) Data 2
+  Data 3 ( 5)------------------------------( 7) Data 3
+  Data 4 ( 6)------------------------------( 8) Data 4
+  Data 5 ( 7)------------------------------( 9) Data 5
+  Data 6 ( 8)------------------------------(10) Data 6
+  Data 7 ( 9)------------------------------(11) Data 7
+         (10)                      [+5v]---( 1) Vdd
+         (11)                      [GND]---( 2) Ground
+         (12)                      [+5v]---(14) Reset
+         (13)                      [GND]---(15) Read / Write
+    Line (14)------------------------------(13) Controller Select 1
+         (15)
+    Init (16)------------------------------(12) Controller Select 2
+  Select (17)------------------------------(16) Data / Instruction
+  Ground (18)---[GND]              [+5v]---(19) LED +
+  Ground (19)---[GND]
+  Ground (20)---[GND]              E    A             Values:
+  Ground (21)---[GND]       [GND]---[P1]---(18) Vee    - R = Resistor = 22 ohm
+  Ground (22)---[GND]                |                 - P1 = Preset = 10 Kohm
+  Ground (23)---[GND]       ----   S ------( 3) V0     - P2 = Preset = 1 Kohm
+  Ground (24)---[GND]       |  |
+  Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+
+
+4. Userspace Programming
+------------------------
+
+The cfag12864bfb describes a framebuffer device (/dev/fbX).
+
+It has a size of 1024 bytes = 1 Kbyte.
+Each bit represents one pixel. If the bit is high, the pixel will
+turn on. If the pixel is low, the pixel will turn off.
+
+You can use the framebuffer as a file: fopen, fwrite, fclose...
+Although the LCD won't get updated until the next refresh time arrives.
+
+Also, you can mmap the framebuffer: open & mmap, munmap & close...
+which is the best option for most uses.
+
+Check samples/auxdisplay/cfag12864b-example.c
+for a real working userspace complete program with usage examples.
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 000000000000..e466f0595248
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+    :maxdepth: 1
+
+    ks0108.rst
+    cfag12864b.rst
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst
new file mode 100644
index 000000000000..c0b7faf73136
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -0,0 +1,50 @@
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
+
+:License:               GPLv2
+:Author & Maintainer:   Miguel Ojeda Sandonis
+:Date:                  2006-10-27
+
+
+
+.. INDEX
+
+        1. DRIVER INFORMATION
+        2. DEVICE INFORMATION
+        3. WIRING
+
+
+1. Driver Information
+---------------------
+
+This driver supports the ks0108 LCD controller.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer:  Samsung
+:Device Name:   KS0108 LCD Controller
+:Device Code:   ks0108
+:Webpage:       -
+:Device Webpage: -
+:Type:          LCD Controller (Liquid Crystal Display Controller)
+:Width:         64
+:Height:        64
+:Colors:        2 (B/N)
+:Pages:         8
+:Addresses:     64 each page
+:Data size:     1 byte each address
+:Memory size:   8 * 64 * 1 = 512 bytes
+
+
+3. Wiring
+---------
+
+The driver supports data parallel port wiring.
+
+If you aren't building LCD related hardware, you should check
+your LCD specific wiring information in the same folder.
+
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
index 1d7d962933be..36d43ae7dc13 100644
--- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
+++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst
@@ -130,12 +130,6 @@ Proportional weight policy files
             dev     weight
             8:16    300
 
-- blkio.leaf_weight[_device]
-        - Equivalents of blkio.weight[_device] for the purpose of
-          deciding how much weight tasks in the given cgroup has while
-          competing with the cgroup's child cgroups. For details,
-          please refer to Documentation/block/cfq-iosched.txt.
-
 - blkio.time
         - disk time allocated to cgroup per device in milliseconds. First
           two fields specify the major and minor number of the device and
diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst
index 75865da2ce14..b02d6dd6c070 100644
--- a/Documentation/filesystems/cifs/AUTHORS
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -1,5 +1,10 @@
+=======
+Authors
+=======
+
 Original Author
-===============
+---------------
+
 Steve French (sfrench@samba.org)
 
 The author wishes to express his appreciation and thanks to:
@@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
 portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
 Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
 for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John 
+operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John
 Newbigin and others for their work on the Linux smbfs module.  Thanks to
 the other members of the Storage Network Industry Association CIFS Technical
 Workgroup for their work specifying this highly complex protocol and finally
@@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
 
 Patch Contributors
 ------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi 
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
 
 
 Test case and Bug Report contributors
diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst
index 1df7f4910eb2..71f2ecb62299 100644
--- a/Documentation/filesystems/cifs/CHANGES
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -1,3 +1,7 @@
+=======
+Changes
+=======
+
 See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
 information (that may be easier to read than parsing the output of
 "git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 000000000000..fad5268635f5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   usage
+   todo
+   changes
+   authors
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst
index 1be3d21c286e..0b98f672d36f 100644
--- a/Documentation/filesystems/cifs/cifs.txt
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -1,3 +1,7 @@
+============
+Introduction
+============
+
   This is the client VFS module for the SMB3 NAS protocol as well
   as for older dialects such as the Common Internet File System (CIFS)
   protocol which was the successor to the Server Message Block
@@ -33,7 +37,9 @@
   tools (including smbinfo and setcifsacl) that can be obtained from
 
       https://git.samba.org/?p=cifs-utils.git
+
   or
+
       git://git.samba.org/cifs-utils.git
 
   mount.cifs should be installed in the directory with the other mount helpers.
@@ -41,5 +47,7 @@
   For more information on the module see the project wiki page at
 
       https://wiki.samba.org/index.php/LinuxCIFS
+
   and
+
       https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst
index edbbccda1942..084c25f92dcb 100644
--- a/Documentation/filesystems/cifs/TODO
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -1,3 +1,7 @@
+====
+TODO
+====
+
 Version 2.14 December 21, 2018
 
 A Partial List of Missing Features
@@ -8,55 +12,58 @@ for visible, important contributions to this module.  Here
 is a partial list of the known problems and missing features:
 
 a) SMB3 (and SMB3.1.1) missing optional features:
+
    - multichannel (started), integration with RDMA
    - directory leases (improved metadata caching), started (root dir only)
    - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
      currently the only two server side copy mechanisms supported)
 
 b) improved sparse file support (fiemap and SEEK_HOLE are implemented
-but additional features would be supportable by the protocol).
+   but additional features would be supportable by the protocol).
 
 c) Directory entry caching relies on a 1 second timer, rather than
-using Directory Leases, currently only the root file handle is cached longer
+   using Directory Leases, currently only the root file handle is cached longer
 
 d) quota support (needs minor kernel change since quota calls
-to make it to network filesystems or deviceless filesystems)
+   to make it to network filesystems or deviceless filesystems)
 
-e) Additional use cases can be optimized to use "compounding"
-(e.g. open/query/close and open/setinfo/close) to reduce the number
-of roundtrips to the server and improve performance. Various cases
-(stat, statfs, create, unlink, mkdir) already have been improved by
-using compounding but more can be done.  In addition we could significantly
-reduce redundant opens by using deferred close (with handle caching leases)
-and better using reference counters on file handles.
+e) Additional use cases can be optimized to use "compounding" (e.g.
+   open/query/close and open/setinfo/close) to reduce the number of
+   roundtrips to the server and improve performance. Various cases
+   (stat, statfs, create, unlink, mkdir) already have been improved by
+   using compounding but more can be done. In addition we could
+   significantly reduce redundant opens by using deferred close (with
+   handle caching leases) and better using reference counters on file
+   handles.
 
 f) Finish inotify support so kde and gnome file list windows
-will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.   
+   will autorefresh (partially complete by Asser). Needs minor kernel
+   vfs change to support removing D_NOTIFY on a file.
 
 g) Add GUI tool to configure /proc/fs/cifs settings and for display of
-the CIFS statistics (started)
+   the CIFS statistics (started)
 
 h) implement support for security and trusted categories of xattrs
-(requires minor protocol extension) to enable better support for SELINUX
+   (requires minor protocol extension) to enable better support for SELINUX
 
 i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
    feature (may be especially useful for virtualization).
 
 j) Create UID mapping facility so server UIDs can be mapped on a per
-mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
+   mount or a per server basis to client UIDs or nobody if no mapping
+   exists. Also better integration with winbind for resolving SID owners
 
 k) Add tools to take advantage of more smb3 specific ioctls and features
-(passthrough ioctl/fsctl is now implemented in cifs.ko to allow sending
-various SMB3 fsctls and query info and set info calls directly from user space)
-Add tools to make setting various non-POSIX metadata attributes easier
-from tools (e.g. extending what was done in smb-info tool).
+   (passthrough ioctl/fsctl is now implemented in cifs.ko to allow
+   sending various SMB3 fsctls and query info and set info calls
+   directly from user space) Add tools to make setting various non-POSIX
+   metadata attributes easier from tools (e.g. extending what was done
+   in smb-info tool).
 
 l) encrypted file support
 
 m) improved stats gathering tools (perhaps integration with nfsometer?)
-to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+   to extend and make easier to use what is currently in /proc/fs/cifs/Stats
 
 n) Add support for claims based ACLs ("DAC")
 
@@ -69,57 +76,58 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
    different servers, and the server we are connected to has gone down.
 
 q) Allow mount.cifs to be more verbose in reporting errors with dialect
-or unsupported feature errors.
+   or unsupported feature errors.
 
 r) updating cifs documentation, and user guide.
 
 s) Addressing bugs found by running a broader set of xfstests in standard
-file system xfstest suite.
+   file system xfstest suite.
 
 t) split cifs and smb3 support into separate modules so legacy (and less
-secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
+   secure) CIFS dialect can be disabled in environments that don't need it
+   and simplify the code.
 
 v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
-so far).
+   so far).
 
 w) Add support for additional strong encryption types, and additional spnego
-authentication mechanisms (see MS-SMB2)
+   authentication mechanisms (see MS-SMB2)
 
 x) Finish support for SMB3.1.1 compression
 
-KNOWN BUGS
-====================================
+Known Bugs
+==========
+
 See http://bugzilla.samba.org - search on product "CifsVFS" for
 current bug list.  Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
 
 1) existing symbolic links (Windows reparse points) are recognized but
-can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
+   can not be created remotely. They are implemented for Samba and those that
+   support the CIFS Unix extensions, although earlier versions of Samba
+   overly restrict the pathnames.
 2) follow_link and readdir code does not follow dfs junctions
-but recognizes them
+   but recognizes them
 
 Misc testing to do
 ==================
 1) check out max path names and max path name components against various server
-types. Try nested symlinks (8 deep). Return max path name in stat -f information
+   types. Try nested symlinks (8 deep). Return max path name in stat -f information
 
 2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
-cifs/smb3 better
+   cifs/smb3 better
 
-3) Additional performance testing and optimization using iozone and similar - 
-there are some easy changes that can be done to parallelize sequential writes,
-and when signing is disabled to request larger read sizes (larger than 
-negotiated size) and send larger write sizes to modern servers.
+3) Additional performance testing and optimization using iozone and similar -
+   there are some easy changes that can be done to parallelize sequential writes,
+   and when signing is disabled to request larger read sizes (larger than
+   negotiated size) and send larger write sizes to modern servers.
 
 4) More exhaustively test against less common servers
 
 5) Continue to extend the smb3 "buildbot" which does automated xfstesting
-against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+   against Windows, Samba and Azure currently - to add additional tests and
+   to allow the buildbot to execute the tests faster. The URL for the
+   buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
 
 6) Address various coverity warnings (most are not bugs per-se, but
-the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
+   the more warnings are addressed, the easier it is to spot real
+   problems that static analyzers will point out in the future).
diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst
index 4a804619cff2..d3fb67b8a976 100644
--- a/Documentation/filesystems/cifs/README
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -1,53 +1,61 @@
+=====
+Usage
+=====
+
 This module supports the SMB3 family of advanced network protocols (as well
 as older dialects, originally called "CIFS" or SMB1).
 
 The CIFS VFS module for Linux supports many advanced network filesystem
 features such as hierarchical DFS like namespace, hardlinks, locking and more.
-It was designed to comply with the SNIA CIFS Technical Reference (which 
-supersedes the 1992 X/Open SMB Standard) as well as to perform best practice 
-practical interoperability with Windows 2000, Windows XP, Samba and equivalent 
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
 servers.  This code was developed in participation with the Protocol Freedom
 Information Foundation.  CIFS and now SMB3 has now become a defacto
 standard for interoperating between Macs and Windows and major NAS appliances.
 
 Please see
-  MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
-  http://protocolfreedom.org/ and
-  http://samba.org/samba/PFIF/
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+http://protocolfreedom.org/ and
+http://samba.org/samba/PFIF/
 for more details.
 
 
 For questions or bug reports please contact:
+
     smfrench@gmail.com
 
 See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
 
-Build instructions:
+Build instructions
 ==================
+
 For Linux:
+
 1) Download the kernel (e.g. from http://www.kernel.org)
-and change directory into the top of the kernel directory tree
-(e.g. /usr/src/linux-2.5.73)
+   and change directory into the top of the kernel directory tree
+   (e.g. /usr/src/linux-2.5.73)
 2) make menuconfig (or make xconfig)
 3) select cifs from within the network filesystem choices
 4) save and exit
 5) make
 
 
-Installation instructions:
+Installation instructions
 =========================
+
 If you have built the CIFS vfs as module (successfully) simply
-type "make modules_install" (or if you prefer, manually copy the file to
+type ``make modules_install`` (or if you prefer, manually copy the file to
 the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
 
 If you have built the CIFS vfs into the kernel itself, follow the instructions
 for your distribution on how to install a new kernel (usually you
-would simply type "make install").
+would simply type ``make install``).
 
 If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
 the CIFS VFS web site) copy it to the same directory in which mount helpers
 reside (usually /sbin).  Although the helper software is not
-required, mount.cifs is recommended.  Most distros include a "cifs-utils"
+required, mount.cifs is recommended.  Most distros include a ``cifs-utils``
 package that includes this utility so it is recommended to install this.
 
 Note that running the Winbind pam/nss module (logon service) on all of your
@@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org
 
 If cifs is built as a module, then the size and number of network buffers
 and maximum number of simultaneous requests to one server can be configured.
-Changing these from their defaults is not recommended. By executing modinfo
+Changing these from their defaults is not recommended. By executing modinfo::
+
         modinfo kernel/fs/cifs/cifs.ko
+
 on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
 at module initialization time (by running insmod cifs.ko) can be seen.
 
 Recommendations
 ===============
+
 To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
 the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
 on mount (or vers=2.0 for Windows Vista).  Note that the CIFS (vers=1.0) is
@@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection
 and encrypted shares and stronger signing and authentication algorithms.
 There are additional mount options that may be helpful for SMB3 to get
 improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
-     "mfsymlinks" and "cifsacl" and "idsfromsid"
+
+     ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid``
 
 Allowing User Mounts
 ====================
+
 To permit users to mount and unmount over directories they own is possible
 with the cifs vfs.  A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to 
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
 umount shares they mount requires
+
 1) mount.cifs version 1.4 or later
 2) an entry for the share in /etc/fstab indicating that a user may
-unmount it e.g.
-//server/usersharename  /mnt/username cifs user 0 0
+   unmount it e.g.::
+
+     //server/usersharename  /mnt/username cifs user 0 0
 
-Note that when the mount.cifs utility is run suid (allowing user mounts), 
-in order to reduce risks, the "nosuid" mount flag is passed in on mount to
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
 disallow execution of an suid program mounted on the remote target.
 When mount is executed as root, nosuid is not passed in by default,
 and execution of suid programs on the remote target would be enabled
-by default. This can be changed, as with nfs and other filesystems, 
-by simply specifying "nosuid" among the mount options. For user mounts 
-though to be able to pass the suid flag to mount requires rebuilding 
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
 mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
 
 There is a corresponding manual page for cifs mounting in the Samba 3.0 and
-later source tree in docs/manpages/mount.cifs.8 
+later source tree in docs/manpages/mount.cifs.8
 
 Allowing User Unmounts
 ======================
+
 To permit users to ummount directories that they have user mounted (see above),
-the utility umount.cifs may be used.  It may be invoked directly, or if 
+the utility umount.cifs may be used.  It may be invoked directly, or if
 umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
 (at least for most versions of the umount utility) for umount of cifs
 mounts, unless umount is invoked with -i (which will avoid invoking a umount
 helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
-as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
 allow adding entries to a file to the /etc/permissions file to achieve the
 equivalent suid effect).  For this utility to succeed the target path
 must be a cifs mount, and the uid of the current user must match the uid
 of the user who mounted the resource.
 
-Also note that the customary way of allowing user mounts and unmounts is 
+Also note that the customary way of allowing user mounts and unmounts is
 (instead of using mount.cifs and unmount.cifs as suid) to add a line
 to the file /etc/fstab for each //server/share you wish to mount, but
 this can become unwieldy when potential mount targets include many
 or  unpredictable UNC names.
 
-Samba Considerations 
+Samba Considerations
 ====================
+
 Most current servers support SMB2.1 and SMB3 which are more secure,
 but there are useful protocol extensions for the older less secure CIFS
 dialect, so to get the maximum benefit if mounting using the older dialect
 (CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
 Unix Extensions standard (e.g. almost any  version of Samba ie version
 2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
-Note that uid, gid and file permissions will display default values if you do 
-not have a server that supports the Unix extensions for CIFS (such as Samba 
-2.2.5 or later).  To enable the Unix CIFS Extensions in the Samba server, add 
-the line: 
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later).  To enable the Unix CIFS Extensions in the Samba server, add
+the line::
 
         unix extensions = yes
-        
-to your smb.conf file on the server.  Note that the following smb.conf settings 
-are also useful (on the Samba server) when the majority of clients are Unix or 
-Linux: 
+
+to your smb.conf file on the server.  Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
 
         case sensitive = yes
-        delete readonly = yes 
+        delete readonly = yes
         ea support = yes
 
 Note that server ea support is required for supporting xattrs from the Linux
-cifs client, and that EA support is present in later versions of Samba (e.g. 
+cifs client, and that EA support is present in later versions of Samba (e.g.
 3.0.6 and later (also EA support works in all versions of Windows, at least to
 shares on NTFS filesystems).  Extended Attribute (xattr) support is an optional
 feature of most Linux filesystems which may require enabling via
 make menuconfig. Client support for extended attributes (user xattr) can be
-disabled on a per-mount basis by specifying "nouser_xattr" on mount.
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
 
 The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
-version 3.10 and later.  Setting POSIX ACLs requires enabling both XATTR and 
+version 3.10 and later.  Setting POSIX ACLs requires enabling both XATTR and
 then POSIX support in the CIFS configuration options when building the cifs
 module.  POSIX ACL support can be disabled on a per mount basic by specifying
-"noacl" on mount.
- 
-Some administrators may want to change Samba's smb.conf "map archive" and 
-"create mask" parameters from the default.  Unless the create mask is changed
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default.  Unless the create mask is changed
 newly created files can end up with an unnecessarily restrictive default mode,
 which may not be what you want, although if the CIFS Unix extensions are
 enabled on the server and client, subsequent setattr calls (e.g. chmod) can
-fix the mode.  Note that creating special devices (mknod) remotely 
-may require specifying a mkdev function to Samba if you are not using 
+fix the mode.  Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
 Samba 3.0.6 or later.  For more information on these see the manual pages
-("man smb.conf") on the Samba server system.  Note that the cifs vfs,
-unlike the smbfs vfs, does not read the smb.conf on the client system 
-(the few optional settings are passed in on mount via -o parameters instead).  
+(``man smb.conf``) on the Samba server system.  Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
 Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
-open files (required for strict POSIX compliance).  Windows Servers already 
+open files (required for strict POSIX compliance).  Windows Servers already
 supported this feature. Samba server does not allow symlinks that refer to files
 outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
-files with absolute paths (ie beginning with slash) such as:
+files with absolute paths (ie beginning with slash) such as::
+
          ln -s /mnt/foo bar
-would be forbidden. Samba 3.0.6 server or later includes the ability to create 
-such symlinks safely by converting unsafe symlinks (ie symlinks to server 
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
 files that are outside of the share) to a samba specific format on the server
 that is ignored by local server applications and non-cifs clients and that will
 not be traversed by the Samba server).  This is opaque to the Linux client
 application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
 later, but only for remote clients using the CIFS Unix extensions, and will
 be invisbile to Windows clients and typically will not affect local
-applications running on the same server as Samba.  
+applications running on the same server as Samba.
 
-Use instructions:
+Use instructions
 ================
-Once the CIFS VFS support is built into the kernel or installed as a module 
+
+Once the CIFS VFS support is built into the kernel or installed as a module
 (cifs.ko), you can use mount syntax like the following to access Samba or
-Mac or Windows servers:
+Mac or Windows servers::
 
   mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
 
 Before -o the option -v may be specified to make the mount.cifs
-mount helper display the mount steps more verbosely.  
+mount helper display the mount steps more verbosely.
 After -o the following commonly used cifs vfs specific options
-are supported:
+are supported::
 
   username=<username>
   password=<password>
   domain=<domain name>
-  
+
 Other cifs mount options are described below.  Use of TCP names (in addition to
 ip addresses) is available if the mount helper (mount.cifs) is installed. If
 you do not trust the server to which are mounted, or if you do not have
 cifs signing enabled (and the physical network is insecure), consider use
-of the standard mount options "noexec" and "nosuid" to reduce the risk of 
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
 running an altered binary on your local system (downloaded from a hostile server
 or altered by a hostile router).
 
 Although mounting using format corresponding to the CIFS URL specification is
 not possible in mount.cifs yet, it is possible to use an alternate format
 for the server and sharename (which is somewhat similar to NFS style mount
-syntax) instead of the more widely used UNC format (i.e. \\server\share):
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
   mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
 
 When using the mount helper mount.cifs, passwords may be specified via alternate
-mechanisms, instead of specifying it after -o using the normal "pass=" syntax
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
 on the command line:
 1) By including it in a credential file. Specify credentials=filename as one
-of the mount options. Credential files contain two lines
-        username=someuser
-        password=your_password
+of the mount options. Credential files contain two lines::
+
+        username=someuser
+        password=your_password
+
 2) By specifying the password in the PASSWD environment variable (similarly
-the user name can be taken from the USER environment variable).
+   the user name can be taken from the USER environment variable).
 3) By specifying the password in a file by name via PASSWD_FILE
 4) By specifying the password in a file by file descriptor via PASSWD_FD
 
@@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry
 
 Restrictions
 ============
-Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC 
-1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a 
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
 problem as most servers support this.
 
 Valid filenames differ between Windows and Linux.  Windows typically restricts
-filenames which contain certain reserved characters (e.g.the character : 
+filenames which contain certain reserved characters (e.g.the character :
 which is used to delimit the beginning of a stream name by Windows), while
 Linux allows a slightly wider set of valid characters in filenames. Windows
 servers can remap such characters when an explicit mapping is specified in
-the Server's registry.  Samba starting with version 3.10 will allow such 
+the Server's registry.  Samba starting with version 3.10 will allow such
 filenames (ie those which contain valid Linux characters, which normally
 would be forbidden for Windows/CIFS semantics) as long as the server is
 configured for Unix Extensions (and the client has not disabled
 /proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
-"mapposix" can be used on CIFS (vers=1.0) to force the mapping of
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
 illegal Windows/NTFS/SMB characters to a remap range (this mount parm
-is the default for SMB3). This remap ("mapposix") range is also
+is the default for SMB3). This remap (``mapposix``) range is also
 compatible with Mac (and "Services for Mac" on some older Windows).
 
 CIFS VFS Mount Options
 ======================
 A partial list of the supported mount options follows:
-  username      The user name to use when trying to establish
+
+  username
+                The user name to use when trying to establish
                 the CIFS session.
-  password      The user password.  If the mount helper is
+  password
+                The user password.  If the mount helper is
                 installed, the user will be prompted for password
                 if not supplied.
-  ip            The ip address of the target server
-  unc           The target server Universal Network Name (export) to 
-                mount.  
-  domain        Set the SMB/CIFS workgroup name prepended to the
+  ip
+                The ip address of the target server
+  unc
+                The target server Universal Network Name (export) to
+                mount.
+  domain
+                Set the SMB/CIFS workgroup name prepended to the
                 username during CIFS session establishment
-  forceuid      Set the default uid for inodes to the uid
+  forceuid
+                Set the default uid for inodes to the uid
                 passed in on mount. For mounts to servers
                 which do support the CIFS Unix extensions, such as a
                 properly configured Samba server, the server provides
@@ -276,32 +307,39 @@ A partial list of the supported mount options follows:
                 extensions, the default uid (and gid) returned on lookup
                 of existing files will be the uid (gid) of the person
                 who executed the mount (root, except when mount.cifs
-                is configured setuid for user mounts) unless the "uid=" 
+                is configured setuid for user mounts) unless the ``uid=``
                 (gid) mount option is specified. Also note that permission
                 checks (authorization checks) on accesses to a file occur
                 at the server, but there are cases in which an administrator
                 may want to restrict at the client as well.  For those
                 servers which do not report a uid/gid owner
                 (such as Windows), permissions can also be checked at the
-                client, and a crude form of client side permission checking 
-                can be enabled by specifying file_mode and dir_mode on 
+                client, and a crude form of client side permission checking
+                can be enabled by specifying file_mode and dir_mode on
                 the client.  (default)
-  forcegid      (similar to above but for the groupid instead of uid) (default)
-  noforceuid    Fill in file owner information (uid) by requesting it from
+  forcegid
+                (similar to above but for the groupid instead of uid) (default)
+  noforceuid
+                Fill in file owner information (uid) by requesting it from
                 the server if possible. With this option, the value given in
                 the uid= option (on mount) will only be used if the server
                 can not support returning uids on inodes.
-  noforcegid    (similar to above but for the group owner, gid, instead of uid)
-  uid           Set the default uid for inodes, and indicate to the
+  noforcegid
+                (similar to above but for the group owner, gid, instead of uid)
+  uid
+                Set the default uid for inodes, and indicate to the
                 cifs kernel driver which local user mounted. If the server
                 supports the unix extensions the default uid is
                 not used to fill in the owner fields of inodes (files)
-                unless the "forceuid" parameter is specified.
-  gid           Set the default gid for inodes (similar to above).
-  file_mode     If CIFS Unix extensions are not supported by the server
+                unless the ``forceuid`` parameter is specified.
+  gid
+                Set the default gid for inodes (similar to above).
+  file_mode
+                If CIFS Unix extensions are not supported by the server
                 this overrides the default mode for file inodes.
-  fsc           Enable local disk caching using FS-Cache (off by default). This
-                option could be useful to improve performance on a slow link,
+  fsc
+                Enable local disk caching using FS-Cache (off by default). This
+                option could be useful to improve performance on a slow link,
                 heavily loaded server and/or network where reading from the
                 disk is faster than reading from the server (over the network).
                 This could also impact scalability positively as the
@@ -310,18 +348,22 @@ A partial list of the supported mount options follows:
                 type workloads. So, you need to consider carefully your
                 workload/scenario before using this option. Currently, local
                 disk caching is functional for CIFS files opened as read-only.
-  dir_mode      If CIFS Unix extensions are not supported by the server 
+  dir_mode
+                If CIFS Unix extensions are not supported by the server
                 this overrides the default mode for directory inodes.
-  port          attempt to contact the server on this tcp port, before
+  port
+                attempt to contact the server on this tcp port, before
                 trying the usual ports (port 445, then 139).
-  iocharset     Codepage used to convert local path names to and from
+  iocharset
+                Codepage used to convert local path names to and from
                 Unicode. Unicode is used by default for network path
                 names if the server supports it.  If iocharset is
                 not specified then the nls_default specified
                 during the local client kernel build will be used.
                 If server does not support Unicode, this parameter is
                 unused.
-  rsize         default read size (usually 16K). The client currently
+  rsize
+                default read size (usually 16K). The client currently
                 can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
                 defaults to 16K and may be changed (from 8K to the maximum
                 kmalloc size allowed by your kernel) at module install time
@@ -333,10 +375,12 @@ A partial list of the supported mount options follows:
                 newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
                 set from a minimum of 2048 to a maximum of 130048 (127K or
                 CIFSMaxBufSize, whichever is smaller)
-  wsize         default write size (default 57344)
+  wsize
+                default write size (default 57344)
                 maximum wsize currently allowed by CIFS is 57344 (fourteen
                 4096 byte pages)
-  actimeo=n     attribute cache timeout in seconds (default 1 second).
+  actimeo=n
+                attribute cache timeout in seconds (default 1 second).
                 After this timeout, the cifs client requests fresh attribute
                 information from the server. This option allows to tune the
                 attribute cache timeout to suit the workload needs. Shorter
@@ -345,49 +389,67 @@ A partial list of the supported mount options follows:
                 of calls to the server at the expense of less stricter cache
                 coherency checks (i.e. incorrect attribute cache for a short
                 period of time).
-  rw            mount the network share read-write (note that the
+  rw
+                mount the network share read-write (note that the
                 server may still consider the share read-only)
-  ro            mount network share read-only
-  version       used to distinguish different versions of the
+  ro
+                mount network share read-only
+  version
+                used to distinguish different versions of the
                 mount helper utility (not typically needed)
-  sep           if first mount option (after the -o), overrides
+  sep
+                if first mount option (after the -o), overrides
                 the comma as the separator between the mount
-                parms. e.g.
+                parms. e.g.::
+
                         -o user=myname,password=mypassword,domain=mydom
-                could be passed instead with period as the separator by
+
+                could be passed instead with period as the separator by::
+
                         -o sep=.user=myname.password=mypassword.domain=mydom
+
                 this might be useful when comma is contained within username
                 or password or domain. This option is less important
                 when the cifs mount helper cifs.mount (version 1.1 or later)
                 is used.
-  nosuid        Do not allow remote executables with the suid bit 
+  nosuid
+                Do not allow remote executables with the suid bit
                 program to be executed.  This is only meaningful for mounts
                 to servers such as Samba which support the CIFS Unix Extensions.
                 If you do not trust the servers in your network (your mount
                 targets) it is recommended that you specify this option for
                 greater security.
-  exec          Permit execution of binaries on the mount.
-  noexec        Do not permit execution of binaries on the mount.
-  dev           Recognize block devices on the remote mount.
-  nodev         Do not recognize devices on the remote mount.
-  suid          Allow remote files on this mountpoint with suid enabled to 
+  exec
+                Permit execution of binaries on the mount.
+  noexec
+                Do not permit execution of binaries on the mount.
+  dev
+                Recognize block devices on the remote mount.
+  nodev
+                Do not recognize devices on the remote mount.
+  suid
+                Allow remote files on this mountpoint with suid enabled to
                 be executed (default for mounts when executed as root,
                 nosuid is default for user mounts).
-  credentials   Although ignored by the cifs kernel component, it is used by 
+  credentials
+                Although ignored by the cifs kernel component, it is used by
                 the mount helper, mount.cifs. When mount.cifs is installed it
-                opens and reads the credential file specified in order  
+                opens and reads the credential file specified in order
                 to obtain the userid and password arguments which are passed to
                 the cifs vfs.
-  guest         Although ignored by the kernel component, the mount.cifs
+  guest
+                Although ignored by the kernel component, the mount.cifs
                 mount helper will not prompt the user for a password
                 if guest is specified on the mount options.  If no
                 password is specified a null password will be used.
-  perm          Client does permission checks (vfs_permission check of uid
+  perm
+                Client does permission checks (vfs_permission check of uid
                 and gid of the file against the mode and desired operation),
                 Note that this is in addition to the normal ACL check on the
-                target machine done by the server software. 
+                target machine done by the server software.
                 Client permission checking is enabled by default.
-  noperm        Client does not do permission checks.  This can expose
+  noperm
+                Client does not do permission checks.  This can expose
                 files on this mount to access by other users on the local
                 client system. It is typically only needed when the server
                 supports the CIFS Unix Extensions but the UIDs/GIDs on the
@@ -399,7 +461,8 @@ A partial list of the supported mount options follows:
                 Note that this does not affect the normal ACL check on the
                 target machine done by the server software (of the server
                 ACL against the user name provided at mount time).
-  serverino     Use server's inode numbers instead of generating automatically
+  serverino
+                Use server's inode numbers instead of generating automatically
                 incrementing inode numbers on the client.  Although this will
                 make it easier to spot hardlinked files (as they will have
                 the same inode numbers) and inode numbers may be persistent,
@@ -412,14 +475,16 @@ A partial list of the supported mount options follows:
                 or the CIFS Unix Extensions equivalent and for those
                 this mount option will have no effect.  Exporting cifs mounts
                 under nfsd requires this mount option on the cifs mount.
-                This is now the default if server supports the 
+                This is now the default if server supports the
                 required network operation.
-  noserverino   Client generates inode numbers (rather than using the actual one
+  noserverino
+                Client generates inode numbers (rather than using the actual one
                 from the server). These inode numbers will vary after
                 unmount or reboot which can confuse some applications,
                 but not all server filesystems support unique inode
                 numbers.
-  setuids       If the CIFS Unix extensions are negotiated with the server
+  setuids
+                If the CIFS Unix extensions are negotiated with the server
                 the client will attempt to set the effective uid and gid of
                 the local process on newly created files, directories, and
                 devices (create, mkdir, mknod).  If the CIFS Unix Extensions
@@ -427,9 +492,10 @@ A partial list of the supported mount options follows:
                 instead of using the default uid and gid specified on
                 the mount, cache the new file's uid and gid locally which means
                 that the uid for the file can change when the inode is
-                reloaded (or the user remounts the share).
-  nosetuids     The client will not attempt to set the uid and gid on
-                on newly created files, directories, and devices (create, 
+                reloaded (or the user remounts the share).
+  nosetuids
+                The client will not attempt to set the uid and gid on
+                on newly created files, directories, and devices (create,
                 mkdir, mknod) which will result in the server setting the
                 uid and gid to the default (usually the server uid of the
                 user who mounted the share).  Letting the server (rather than
@@ -437,38 +503,49 @@ A partial list of the supported mount options follows:
                 Unix Extensions are not negotiated then the uid and gid for
                 new files will appear to be the uid (gid) of the mounter or the
                 uid (gid) parameter specified on the mount.
-  netbiosname   When mounting to servers via port 139, specifies the RFC1001
-                source name to use to represent the client netbios machine 
+  netbiosname
+                When mounting to servers via port 139, specifies the RFC1001
+                source name to use to represent the client netbios machine
                 name when doing the RFC1001 netbios session initialize.
-  direct        Do not do inode data caching on files opened on this mount.
+  direct
+                Do not do inode data caching on files opened on this mount.
                 This precludes mmapping files on this mount. In some cases
                 with fast networks and little or no caching benefits on the
                 client (e.g. when the application is doing large sequential
-                reads bigger than page size without rereading the same data) 
+                reads bigger than page size without rereading the same data)
                 this can provide better performance than the default
-                behavior which caches reads (readahead) and writes 
-                (writebehind) through the local Linux client pagecache 
+                behavior which caches reads (readahead) and writes
+                (writebehind) through the local Linux client pagecache
                 if oplock (caching token) is granted and held. Note that
                 direct allows write operations larger than page size
                 to be sent to the server.
-  strictcache   Use for switching on strict cache mode. In this mode the
+  strictcache
+                Use for switching on strict cache mode. In this mode the
                 client read from the cache all the time it has Oplock Level II,
                 otherwise - read from the server. All written data are stored
                 in the cache, but if the client doesn't have Exclusive Oplock,
                 it writes the data to the server.
-  rwpidforward  Forward pid of a process who opened a file to any read or write
+  rwpidforward
+                Forward pid of a process who opened a file to any read or write
                 operation on that file. This prevent applications like WINE
                 from failing on read and write if we use mandatory brlock style.
-  acl           Allow setfacl and getfacl to manage posix ACLs if server
+  acl
+                Allow setfacl and getfacl to manage posix ACLs if server
                 supports them.  (default)
-  noacl         Do not allow setfacl and getfacl calls on this mount
-  user_xattr    Allow getting and setting user xattrs (those attributes whose
-                name begins with "user." or "os2.") as OS/2 EAs (extended
+  noacl
+                Do not allow setfacl and getfacl calls on this mount
+  user_xattr
+                Allow getting and setting user xattrs (those attributes whose
+                name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
                 attributes) to the server.  This allows support of the
                 setfattr and getfattr utilities. (default)
-  nouser_xattr  Do not allow getfattr/setfattr to get/set/list xattrs 
-  mapchars      Translate six of the seven reserved characters (not backslash)
+  nouser_xattr
+                Do not allow getfattr/setfattr to get/set/list xattrs
+  mapchars
+                Translate six of the seven reserved characters (not backslash)::
+
                         *?<>|:
+
                 to the remap range (above 0xF000), which also
                 allows the CIFS client to recognize files created with
                 such characters by Windows's POSIX emulation. This can
@@ -477,39 +554,47 @@ A partial list of the supported mount options follows:
                 whose names contain any of these seven characters).
                 This has no effect if the server does not support
                 Unicode on the wire.
- nomapchars     Do not translate any of these seven characters (default).
- nocase         Request case insensitive path name matching (case
+  nomapchars
+                Do not translate any of these seven characters (default).
+  nocase
+                Request case insensitive path name matching (case
                 sensitive is the default if the server supports it).
-                (mount option "ignorecase" is identical to "nocase")
- posixpaths     If CIFS Unix extensions are supported, attempt to
+                (mount option ``ignorecase`` is identical to ``nocase``)
+  posixpaths
+                If CIFS Unix extensions are supported, attempt to
                 negotiate posix path name support which allows certain
                 characters forbidden in typical CIFS filenames, without
                 requiring remapping. (default)
- noposixpaths   If CIFS Unix extensions are supported, do not request
+  noposixpaths
+                If CIFS Unix extensions are supported, do not request
                 posix path name support (this may cause servers to
                 reject creatingfile with certain reserved characters).
- nounix         Disable the CIFS Unix Extensions for this mount (tree
+  nounix
+                Disable the CIFS Unix Extensions for this mount (tree
                 connection). This is rarely needed, but it may be useful
                 in order to turn off multiple settings all at once (ie
                 posix acls, posix locks, posix paths, symlink support
                 and retrieving uids/gids/mode from the server) or to
                 work around a bug in server which implement the Unix
                 Extensions.
- nobrl          Do not send byte range lock requests to the server.
+  nobrl
+                Do not send byte range lock requests to the server.
                 This is necessary for certain applications that break
                 with cifs style mandatory byte range locks (and most
                 cifs servers do not yet support requesting advisory
                 byte range locks).
- forcemandatorylock Even if the server supports posix (advisory) byte range
+  forcemandatorylock
+                Even if the server supports posix (advisory) byte range
                 locking, send only mandatory lock requests.  For some
                 (presumably rare) applications, originally coded for
                 DOS/Windows, which require Windows style mandatory byte range
                 locking, they may be able to take advantage of this option,
                 forcing the cifs client to only send mandatory locks
                 even if the cifs server would support posix advisory locks.
-                "forcemand" is accepted as a shorter form of this mount
+                ``forcemand`` is accepted as a shorter form of this mount
                 option.
- nostrictsync   If this mount option is set, when an application does an
+  nostrictsync
+                If this mount option is set, when an application does an
                 fsync call then the cifs client does not send an SMB Flush
                 to the server (to force the server to write all dirty data
                 for this file immediately to disk), although cifs still sends
@@ -522,41 +607,50 @@ A partial list of the supported mount options follows:
                 crash.  If this mount option is not set, by default cifs will
                 send an SMB flush request (and wait for a response) on every
                 fsync call.
- nodfs          Disable DFS (global name space support) even if the
+  nodfs
+                Disable DFS (global name space support) even if the
                 server claims to support it.  This can help work around
                 a problem with parsing of DFS paths with Samba server
                 versions 3.0.24 and 3.0.25.
- remount        remount the share (often used to change from ro to rw mounts
-                or vice versa)
- cifsacl        Report mode bits (e.g. on stat) based on the Windows ACL for
-                the file. (EXPERIMENTAL)
- servern        Specify the server 's netbios name (RFC1001 name) to use
-                when attempting to setup a session to the server. 
+  remount
+                remount the share (often used to change from ro to rw mounts
+                or vice versa)
+  cifsacl
+                Report mode bits (e.g. on stat) based on the Windows ACL for
+                the file. (EXPERIMENTAL)
+  servern
+                Specify the server 's netbios name (RFC1001 name) to use
+                when attempting to setup a session to the server.
                 This is needed for mounting to some older servers (such
                 as OS/2 or Windows 98 and Windows ME) since they do not
                 support a default server name.  A server name can be up
                 to 15 characters long and is usually uppercased.
- sfu            When the CIFS Unix Extensions are not negotiated, attempt to
+  sfu
+                When the CIFS Unix Extensions are not negotiated, attempt to
                 create device files and fifos in a format compatible with
                 Services for Unix (SFU).  In addition retrieve bits 10-12
                 of the mode via the SETFILEBITS extended attribute (as
                 SFU does).  In the future the bottom 9 bits of the
                 mode also will be emulated using queries of the security
                 descriptor (ACL).
- mfsymlinks     Enable support for Minshall+French symlinks
+  mfsymlinks
+                Enable support for Minshall+French symlinks
                 (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
                 This option is ignored when specified together with the
                 'sfu' option. Minshall+French symlinks are used even if
                 the server supports the CIFS Unix Extensions.
- sign           Must use packet signing (helps avoid unwanted data modification
+  sign
+                Must use packet signing (helps avoid unwanted data modification
                 by intermediate systems in the route).  Note that signing
                 does not work with lanman or plaintext authentication.
- seal           Must seal (encrypt) all data on this mounted share before
+  seal
+                Must seal (encrypt) all data on this mounted share before
                 sending on the network.  Requires support for Unix Extensions.
                 Note that this differs from the sign mount option in that it
                 causes encryption of data sent over this mounted share but other
                 shares mounted to the same server are unaffected.
- locallease     This option is rarely needed. Fcntl F_SETLEASE is
+  locallease
+                This option is rarely needed. Fcntl F_SETLEASE is
                 used by some applications such as Samba and NFSv4 server to
                 check to see whether a file is cacheable.  CIFS has no way
                 to explicitly request a lease, but can check whether a file
@@ -569,51 +663,73 @@ A partial list of the supported mount options follows:
                 will allow the cifs client to check for leases (only) locally
                 for files which are not oplocked instead of denying leases
                 in that case. (EXPERIMENTAL)
- sec            Security mode.  Allowed values are:
-                        none    attempt to connection as a null user (no name)
-                        krb5    Use Kerberos version 5 authentication
-                        krb5i   Use Kerberos authentication and packet signing
-                        ntlm    Use NTLM password hashing (default)
-                        ntlmi   Use NTLM password hashing with signing (if
+  sec
+                Security mode.  Allowed values are:
+
+                        none
+                                attempt to connection as a null user (no name)
+                        krb5
+                                Use Kerberos version 5 authentication
+                        krb5i
+                                Use Kerberos authentication and packet signing
+                        ntlm
+                                Use NTLM password hashing (default)
+                        ntlmi
+                                Use NTLM password hashing with signing (if
                                 /proc/fs/cifs/PacketSigningEnabled on or if
-                                server requires signing also can be the default) 
-                        ntlmv2  Use NTLMv2 password hashing      
-                        ntlmv2i Use NTLMv2 password hashing with packet signing
-                        lanman  (if configured in kernel config) use older
+                                server requires signing also can be the default)
+                        ntlmv2
+                                Use NTLMv2 password hashing
+                        ntlmv2i
+                                Use NTLMv2 password hashing with packet signing
+                        lanman
+                                (if configured in kernel config) use older
                                 lanman hash
-hard            Retry file operations if server is not responding
-soft            Limit retries to unresponsive servers (usually only
+  hard
+                Retry file operations if server is not responding
+  soft
+                Limit retries to unresponsive servers (usually only
                 one retry) before returning an error.  (default)
 
 The mount.cifs mount helper also accepts a few mount options before -o
 including:
 
+=============== ===============================================================
         -S      take password from stdin (equivalent to setting the environment
-                variable "PASSWD_FD=0"
+                variable ``PASSWD_FD=0``
         -V      print mount.cifs version
         -?      display simple usage information
+=============== ===============================================================
 
 With most 2.6 kernel versions of modutils, the version of the cifs kernel
 module can be displayed via modinfo.
 
 Misc /proc/fs/cifs Flags and Debug Info
 =======================================
+
 Informational pseudo-files:
+
+======================= =======================================================
 DebugData               Displays information about active CIFS sessions and
                         shares, features enabled as well as the cifs.ko
                         version.
 Stats                   Lists summary resource usage information as well as per
                         share statistics.
+======================= =======================================================
 
 Configuration pseudo-files:
+
+======================= =======================================================
 SecurityFlags           Flags which control security negotiation and
                         also packet signing. Authentication (may/must)
                         flags (e.g. for NTLM and/or NTLMv2) may be combined with
                         the signing flags.  Specifying two different password
-                        hashing mechanisms (as "must use") on the other hand 
-                        does not make much sense. Default flags are 
-                                0x07007 
-                        (NTLM, NTLMv2 and packet signing allowed).  The maximum 
+                        hashing mechanisms (as "must use") on the other hand
+                        does not make much sense. Default flags are::
+
+                                0x07007
+
+                        (NTLM, NTLMv2 and packet signing allowed).  The maximum
                         allowable flags if you want to allow mounts to servers
                         using weaker password hashes is 0x37037 (lanman,
                         plaintext, ntlm, ntlmv2, signing allowed).  Some
@@ -626,21 +742,21 @@ SecurityFlags		Flags which control security negotiation and
                         laintext passwords using the older lanman dialect
                         form of the session setup SMB.  (e.g. for authentication
                         using plain text passwords, set the SecurityFlags
-                        to 0x30030):
- 
-                        may use packet signing                          0x00001
-                        must use packet signing                         0x01001
-                        may use NTLM (most common password hash)        0x00002
-                        must use NTLM                                   0x02002
-                        may use NTLMv2                                  0x00004
-                        must use NTLMv2                                 0x04004
-                        may use Kerberos security                       0x00008
-                        must use Kerberos                               0x08008
-                        may use lanman (weak) password hash             0x00010
-                        must use lanman password hash                   0x10010
-                        may use plaintext passwords                     0x00020
-                        must use plaintext passwords                    0x20020
-                        (reserved for future packet encryption)         0x00040
+                        to 0x30030)::
+
+                          may use packet signing                        0x00001
+                          must use packet signing                       0x01001
+                          may use NTLM (most common password hash)      0x00002
+                          must use NTLM                                 0x02002
+                          may use NTLMv2                                0x00004
+                          must use NTLMv2                               0x04004
+                          may use Kerberos security                     0x00008
+                          must use Kerberos                             0x08008
+                          may use lanman (weak) password hash           0x00010
+                          must use lanman password hash                 0x10010
+                          may use plaintext passwords                   0x00020
+                          must use plaintext passwords                  0x20020
+                          (reserved for future packet encryption)       0x00040
 
 cifsFYI                 If set to non-zero value, additional debug information
                         will be logged to the system error log.  This field
@@ -650,14 +766,19 @@ cifsFYI			If set to non-zero value, additional debug information
                         Some debugging statements are not compiled into the
                         cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
                         kernel configuration. cifsFYI may be set to one or
-                        nore of the following flags (7 sets them all):
-
-                        log cifs informational messages                 0x01
-                        log return codes from cifs entry points         0x02
-                        log slow responses (ie which take longer than 1 second)
-                          CONFIG_CIFS_STATS2 must be enabled in .config 0x04
-                                
-                                
+                        nore of the following flags (7 sets them all)::
+
+                          +-----------------------------------------------+------+
+                          | log cifs informational messages               | 0x01 |
+                          +-----------------------------------------------+------+
+                          | log return codes from cifs entry points       | 0x02 |
+                          +-----------------------------------------------+------+
+                          | log slow responses                            | 0x04 |
+                          | (ie which take longer than 1 second)          |      |
+                          |                                               |      |
+                          | CONFIG_CIFS_STATS2 must be enabled in .config |      |
+                          +-----------------------------------------------+------+
+
 traceSMB                If set to one, debug information is logged to the
                         system error log with the start of smb requests
                         and responses (default 0)
@@ -671,24 +792,25 @@ LinuxExtensionsEnabled	If set to one then the client will attempt to
                         as support symbolic links. If you use servers
                         such as Samba that support the CIFS Unix
                         extensions but do not want to use symbolic link
-                        support and want to map the uid and gid fields 
-                        to values supplied at mount (rather than the 
+                        support and want to map the uid and gid fields
+                        to values supplied at mount (rather than the
                         actual values, then set this to zero. (default 1)
+======================= =======================================================
 
-These experimental features and tracing can be enabled by changing flags in 
-/proc/fs/cifs (after the cifs module has been installed or built into the 
-kernel, e.g.  insmod cifs).  To enable a feature set it to 1 e.g.  to enable 
-tracing to the kernel message log type: 
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g.  insmod cifs).  To enable a feature set it to 1 e.g.  to enable
+tracing to the kernel message log type::
 
         echo 7 > /proc/fs/cifs/cifsFYI
-        
+
 cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
 logging of various informational messages.  2 enables logging of non-zero
 SMB return codes while 4 enables logging of requests that take longer
-than one second to complete (except for byte range lock requests). 
+than one second to complete (except for byte range lock requests).
 Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
 (.config). Setting it to seven enables all three.  Finally, tracing
-the start of smb requests and responses can be enabled via:
+the start of smb requests and responses can be enabled via::
 
         echo 1 > /proc/fs/cifs/traceSMB
 
@@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.
 Also recorded is the total bytes read and bytes written to the server for
 that share.  Note that due to client caching effects this can be less than the
 number of bytes read and written by the application running on the client.
-Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
 useful if comparing performance of two different scenarios.
-        
-Also note that "cat /proc/fs/cifs/DebugData" will display information about
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
 the active sessions and the shares that are mounted.
 
 Enabling Kerberos (extended security) works but requires version 1.2 or later
@@ -725,19 +847,23 @@ space to ease network configuration and improve reliability.
 
 To use cifs Kerberos and DFS support, the Linux keyutils package should be
 installed and something like the following lines should be added to the
-/etc/request-key.conf file:
+/etc/request-key.conf file::
 
-create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
-create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+  create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+  create dns_resolver * * /usr/local/sbin/cifs.upcall %k
 
 CIFS kernel module parameters
 =============================
 These module parameters can be specified or modified either during the time of
-module loading or during the runtime by using the interface
+module loading or during the runtime by using the interface::
+
         /proc/module/cifs/parameters/<param>
 
-i.e. echo "value" > /sys/module/cifs/parameters/<param>
+i.e.::
 
-1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default.
-                    [Y/y/1]. To disable use any of [N/n/0].
+    echo "value" > /sys/module/cifs/parameters/<param>
 
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+                  [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
index 322a9c833f23..322a9c833f23 100755
--- a/Documentation/filesystems/cifs/winucase_convert.pl
+++ b/Documentation/admin-guide/cifs/winucase_convert.pl
diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt
index e56e00655153..1c5d2281efc9 100644
--- a/Documentation/admin-guide/devices.txt
+++ b/Documentation/admin-guide/devices.txt
@@ -1647,8 +1647,17 @@
                   0 = /dev/comedi0      First comedi device
                   1 = /dev/comedi1      Second comedi device
                     ...
+                 47 = /dev/comedi47     48th comedi device
 
-                See http://stm.lbl.gov/comedi.
+                Minors 48 to 255 are reserved for comedi subdevices with
+                pathnames of the form "/dev/comediX_subdY", where "X" is the
+                minor number of the associated comedi device and "Y" is the
+                subdevice number.  These subdevice minors are assigned
+                dynamically, so there is no fixed mapping from subdevice
+                pathnames to minor numbers.
+
+                See http://www.comedi.org/ for information about the Comedi
+                project.
 
   98 block      User-mode virtual block device
                   0 = /dev/ubda         First user-mode block device
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 33feab2f4084..34cc20ee7f3a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -77,7 +77,10 @@ configure specific aspects of kernel behavior to your liking.
    blockdev/index
    ext4
    binderfs
+   cifs/index
    xfs
+   jfs
+   ufs
    pm/index
    thunderbolt
    LSM/index
@@ -98,6 +101,7 @@ configure specific aspects of kernel behavior to your liking.
    iostats
    kernel-per-CPU-kthreads
    laptops/index
+   auxdisplay/index
    lcd-panel-cgram
    ldm
    lockup-watchdogs
@@ -105,6 +109,7 @@ configure specific aspects of kernel behavior to your liking.
    pnp
    rtc
    svga
+   wimax/index
    video-output
 
 .. only::  subproject and html
diff --git a/Documentation/filesystems/jfs.txt b/Documentation/admin-guide/jfs.rst
index 41fd757997b3..9e12d936bc90 100644
--- a/Documentation/filesystems/jfs.txt
+++ b/Documentation/admin-guide/jfs.rst
@@ -1,45 +1,59 @@
+===========================================
 IBM's Journaled File System (JFS) for Linux
+===========================================
 
 JFS Homepage:  http://jfs.sourceforge.net/
 
 The following mount options are supported:
+
 (*) == default
 
-iocharset=name  Character set to use for converting from Unicode to
+iocharset=name
+                Character set to use for converting from Unicode to
                 ASCII.  The default is to do no conversion.  Use
                 iocharset=utf8 for UTF-8 translations.  This requires
                 CONFIG_NLS_UTF8 to be set in the kernel .config file.
                 iocharset=none specifies the default behavior explicitly.
 
-resize=value    Resize the volume to <value> blocks.  JFS only supports
+resize=value
+                Resize the volume to <value> blocks.  JFS only supports
                 growing a volume, not shrinking it.  This option is only
                 valid during a remount, when the volume is mounted
                 read-write.  The resize keyword with no value will grow
                 the volume to the full size of the partition.
 
-nointegrity     Do not write to the journal.  The primary use of this option
+nointegrity
+                Do not write to the journal.  The primary use of this option
                 is to allow for higher performance when restoring a volume
                 from backup media.  The integrity of the volume is not
                 guaranteed if the system abnormally abends.
 
-integrity(*)    Commit metadata changes to the journal.  Use this option to
+integrity(*)
+                Commit metadata changes to the journal.  Use this option to
                 remount a volume where the nointegrity option was
                 previously specified in order to restore normal behavior.
 
-errors=continue         Keep going on a filesystem error.
-errors=remount-ro(*)    Remount the filesystem read-only on an error.
-errors=panic            Panic and halt the machine if an error occurs.
+errors=continue
+                        Keep going on a filesystem error.
+errors=remount-ro(*)
+                        Remount the filesystem read-only on an error.
+errors=panic
+                        Panic and halt the machine if an error occurs.
 
-uid=value       Override on-disk uid with specified value
-gid=value       Override on-disk gid with specified value
-umask=value     Override on-disk umask with specified octal value.  For
-                directories, the execute bit will be set if the corresponding
+uid=value
+                Override on-disk uid with specified value
+gid=value
+                Override on-disk gid with specified value
+umask=value
+                Override on-disk umask with specified octal value. For
+                directories, the execute bit will be set if the corresponding
                 read bit is set.
 
-discard=minlen  This enables/disables the use of discard/TRIM commands.
-discard         The discard/TRIM commands are sent to the underlying
-nodiscard(*)    block device when blocks are freed. This is useful for SSD
-                devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl
+discard=minlen, discard/nodiscard(*)
+                This enables/disables the use of discard/TRIM commands.
+                The discard/TRIM commands are sent to the underlying
+                block device when blocks are freed. This is useful for SSD
+                devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl
                 command is also available together with the nodiscard option.
                 The value of minlen specifies the minimum blockcount, when
                 a TRIM command to the block device is considered useful.
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 520dedae7150..3e2d22eb5e59 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1044,6 +1044,10 @@
                         specified address. The serial port must already be
                         setup and configured. Options are not yet supported.
 
+                sbi
+                        Use RISC-V SBI (Supervisor Binary Interface) for early
+                        console.
+
                 smh     Use ARM semihosting calls for early console.
 
                 s3c2410,<addr>
diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst
index 7b9035c01a2e..72b2cfb066f4 100644
--- a/Documentation/admin-guide/sysrq.rst
+++ b/Documentation/admin-guide/sysrq.rst
@@ -171,22 +171,20 @@ It seems others find it useful as (System Attention Key) which is
 useful when you want to exit a program that will not let you switch consoles.
 (For example, X or a svgalib program.)
 
-``reboot(b)`` is good when you're unable to shut down. But you should also
-``sync(s)`` and ``umount(u)`` first.
+``reboot(b)`` is good when you're unable to shut down, it is an equivalent
+of pressing the "reset" button.
 
 ``crash(c)`` can be used to manually trigger a crashdump when the system is hung.
 Note that this just triggers a crash if there is no dump mechanism available.
 
-``sync(s)`` is great when your system is locked up, it allows you to sync your
-disks and will certainly lessen the chance of data loss and fscking. Note
-that the sync hasn't taken place until you see the "OK" and "Done" appear
-on the screen. (If the kernel is really in strife, you may not ever get the
-OK or Done message...)
+``sync(s)`` is handy before yanking removable medium or after using a rescue
+shell that provides no graceful shutdown -- it will ensure your data is
+safely written to the disk. Note that the sync hasn't taken place until you see
+the "OK" and "Done" appear on the screen.
 
-``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally
-``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved
-me many a fsck. Again, the unmount (remount read-only) hasn't taken place until
-you see the "OK" and "Done" message appear on the screen.
+``umount(u)`` can be used to mark filesystems as properly unmounted. From the
+running system's point of view, they will be remounted read-only. The remount
+isn't complete until you see the "OK" and "Done" message appear on the screen.
 
 The loglevels ``0``-``9`` are useful when your console is being flooded with
 kernel messages you do not want to see. Selecting ``0`` will prevent all but
diff --git a/Documentation/filesystems/ufs.txt b/Documentation/admin-guide/ufs.rst
index 7a602adeca2b..55d15297f8d7 100644
--- a/Documentation/filesystems/ufs.txt
+++ b/Documentation/admin-guide/ufs.rst
@@ -1,37 +1,45 @@
-USING UFS
+=========
+Using UFS
 =========
 
 mount -t ufs -o ufstype=type_of_ufs device dir
 
 
-UFS OPTIONS
+UFS Options
 ===========
 
 ufstype=type_of_ufs
         UFS is a file system widely used in different operating systems.
         The problem are differences among implementations. Features of
         some implementations are undocumented, so its hard to recognize
-        type of ufs automatically. That's why user must specify type of 
+        type of ufs automatically. That's why user must specify type of
         ufs manually by mount option ufstype. Possible values are:
 
-        old     old format of ufs
+        old
+                old format of ufs
                 default value, supported as read-only
 
-        44bsd   used in FreeBSD, NetBSD, OpenBSD
+        44bsd
+                used in FreeBSD, NetBSD, OpenBSD
                 supported as read-write
 
-        ufs2    used in FreeBSD 5.x
+        ufs2
+                used in FreeBSD 5.x
                 supported as read-write
 
-        5xbsd   synonym for ufs2
+        5xbsd
+                synonym for ufs2
 
-        sun     used in SunOS (Solaris)
+        sun
+                used in SunOS (Solaris)
                 supported as read-write
 
-        sunx86  used in SunOS for Intel (Solarisx86)
+        sunx86
+                used in SunOS for Intel (Solarisx86)
                 supported as read-write
 
-        hp      used in HP-UX
+        hp
+                used in HP-UX
                 supported as read-only
 
         nextstep
@@ -47,14 +55,14 @@ ufstype=type_of_ufs
                 supported as read-only
 
 
-POSSIBLE PROBLEMS
-=================
+Possible Problems
+-----------------
 
 See next section, if you have any.
 
 
-BUG REPORTS
-===========
+Bug Reports
+-----------
 
 Any ufs bug report you can send to daniel.pirkl@email.cz or
 to dushistov@mail.ru (do not send partition tables bug reports).
diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst
index 7dffd8919cb0..194388c0c351 100644
--- a/Documentation/wimax/README.i2400m
+++ b/Documentation/admin-guide/wimax/i2400m.rst
@@ -1,18 +1,23 @@
+.. include:: <isonum.txt>
 
-   Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
+Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
 
-   (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
 
    This provides a driver for the Intel Wireless WiMAX Connection 2400m
    and a basic Linux kernel WiMAX stack.
 
 1. Requirements
+===============
 
      * Linux installation with Linux kernel 2.6.22 or newer (if building
        from a separate tree)
      * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
        Wireless WiMAX/WiFi Link 5x50 series.
      * build tools:
+
           + Linux kernel development package for the target kernel; to
             build against your currently running kernel, you need to have
             the kernel development package corresponding to the running
@@ -22,8 +27,10 @@
           + GNU C Compiler, make
 
 2. Compilation and installation
+===============================
 
 2.1. Compilation of the drivers included in the kernel
+------------------------------------------------------
 
    Configure the kernel; to enable the WiMAX drivers select Drivers >
    Networking Drivers > WiMAX device support. Enable all of them as
@@ -36,37 +43,39 @@
    Compile and install your kernel as usual.
 
 2.2. Compilation of the drivers distributed as an standalone module
+-------------------------------------------------------------------
 
-   To compile
+   To compile::
 
-$ cd source/directory
-$ make
+        $ cd source/directory
+        $ make
 
    Once built you can load and unload using the provided load.sh script;
    load.sh will load the modules, load.sh u will unload them.
 
    To install in the default kernel directories (and enable auto loading
-   when the device is plugged):
+   when the device is plugged)::
 
-$ make install
-$ depmod -a
+        $ make install
+        $ depmod -a
 
    If your kernel development files are located in a non standard
    directory or if you want to build for a kernel that is not the
-   currently running one, set KDIR to the right location:
+   currently running one, set KDIR to the right location::
 
-$ make KDIR=/path/to/kernel/dev/tree
+        $ make KDIR=/path/to/kernel/dev/tree
 
    For more information, please contact linux-wimax@intel.com.
 
 3. Installing the firmware
+--------------------------
 
    The firmware can be obtained from http://linuxwimax.org or might have
    been supplied with your hardware.
 
-   It has to be installed in the target system:
-     *
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+   It has to be installed in the target system::
+
+        $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
 
      * NOTE: if your firmware came in an .rpm or .deb file, just install
        it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
@@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
        with other types.
 
 4. Design
+=========
 
    This package contains two major parts: a WiMAX kernel stack and a
    driver for the Intel i2400m.
@@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
    API calls should be replaced with the target OS's.
 
 5. Usage
+========
 
    To load the driver, follow the instructions in the install section;
    once the driver is loaded, plug in the device (unless it is permanently
    plugged in). The driver will enumerate the device, upload the firmware
    and output messages in the kernel log (dmesg, /var/log/messages or
-   /var/log/kern.log) such as:
+   /var/log/kern.log) such as::
 
-...
-i2400m_usb 5-4:1.0: firmware interface version 8.0.0
-i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
+        ...
+        i2400m_usb 5-4:1.0: firmware interface version 8.0.0
+        i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
 
    At this point the device is ready to work.
 
@@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
    on how to scan, connect and disconnect.
 
 5.1. Module parameters
+----------------------
 
    Module parameters can be set at kernel or module load time or by
-   echoing values:
+   echoing values::
 
-$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
+        $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
 
    To make changes permanent, for example, for the i2400m module, you can
-   also create a file named /etc/modprobe.d/i2400m containing:
+   also create a file named /etc/modprobe.d/i2400m containing::
 
-options i2400m idle_mode_disabled=1
+        options i2400m idle_mode_disabled=1
 
-   To find which parameters are supported by a module, run:
+   To find which parameters are supported by a module, run::
 
-$ modinfo path/to/module.ko
+        $ modinfo path/to/module.ko
 
    During kernel bootup (if the driver is linked in the kernel), specify
-   the following to the kernel command line:
+   the following to the kernel command line::
 
-i2400m.PARAMETER=VALUE
+        i2400m.PARAMETER=VALUE
 
 5.1.1. i2400m: idle_mode_disabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The i2400m module supports a parameter to disable idle mode. This
    parameter, once set, will take effect only when the device is
    reinitialized by the driver (eg: following a reset or a reconnect).
 
 5.2. Debug operations: debugfs entries
+--------------------------------------
 
    The driver will register debugfs entries that allow the user to tweak
    debug settings. There are three main container directories where
    entries are placed, which correspond to the three blocks a i2400m WiMAX
    driver has:
+
      * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
        controls
      * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
@@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE
    /sys/kernel/debug, those paths will change.
 
 5.2.1. Increasing debug output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The files named *dl_* indicate knobs for controlling the debug output
-   of different submodules:
-     *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+   of different submodules::
+
+        # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+        /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
+        /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+        /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
+        /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+        /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+        /sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
 
    By reading the file you can obtain the current value of said debug
    level; by writing to it, you can set it.
 
    To increase the debug level of, for example, the i2400m's generic TX
-   engine, just write:
+   engine, just write::
 
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+        $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
 
    Increasing numbers yield increasing debug information; for details of
    what is printed and the available levels, check the source. The code
    uses 0 for disabled and increasing values until 8.
 
 5.2.2. RX and TX statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
-   data reception/delivery from the device:
+   data reception/delivery from the device::
 
-$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
+        $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
+        45 1 3 34 3104 48 480
+
+   The numbers reported are:
 
-   The numbers reported are
      * packets/RX-buffer: total, min, max
      * RX-buffers: total RX buffers received, accumulated RX buffer size
        in bytes, min size received, max size received
@@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
    Thus, to find the average buffer size received, divide accumulated
    RX-buffer / total RX-buffers.
 
-   To clear the statistics back to 0, write anything to the rx_stats file:
+   To clear the statistics back to 0, write anything to the rx_stats file::
 
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
+        $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
 
    Likewise for TX.
 
@@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
    to the host. See drivers/net/wimax/i2400m/tx.c.
 
 5.2.3. Tracing messages received from user space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    To echo messages received from user space into the trace pipe that the
    i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
-   1:
-     *
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+   1::
+
+        $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
 
 5.2.4. Performing a device reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    By writing a 0, a 1 or a 2 to the file
    /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
@@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
    (bus specific) reset on the device.
 
 5.2.5. Asking the device to enter power saving mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
    device will attempt to enter power saving mode.
 
 6. Troubleshooting
+==================
 
-6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
+6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
+----------------------------------------------------------------------
 
    If upon connecting the device, the following is output in the kernel
-   log:
+   log::
 
-i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
+        i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
 
    This means that the driver cannot locate the firmware file named
    /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst
new file mode 100644
index 000000000000..fdf7c1f99ff5
--- /dev/null
+++ b/Documentation/admin-guide/wimax/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+WiMAX subsystem
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   wimax
+
+   i2400m
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst
index b78c4378084e..817ee8ba2732 100644
--- a/Documentation/wimax/README.wimax
+++ b/Documentation/admin-guide/wimax/wimax.rst
@@ -1,12 +1,16 @@
+.. include:: <isonum.txt>
 
-   Linux kernel WiMAX stack
+========================
+Linux kernel WiMAX stack
+========================
 
-   (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
 
    This provides a basic Linux kernel WiMAX stack to provide a common
    control API for WiMAX devices, usable from kernel and user space.
 
 1. Design
+=========
 
    The WiMAX stack is designed to provide for common WiMAX control
    services to current and future WiMAX devices from any vendor.
@@ -31,6 +35,7 @@
    include/linux/wimax.h.
 
 2. Usage
+========
 
    For usage in a driver (registration, API, etc) please refer to the
    instructions in the header file include/linux/wimax.h.
@@ -40,6 +45,7 @@
    control.
 
 2.1. Obtaining debug information: debugfs entries
+-------------------------------------------------
 
    The WiMAX stack is compiled, by default, with debug messages that can
    be used to diagnose issues. By default, said messages are disabled.
@@ -52,20 +58,22 @@
    create more subentries below it.
 
 2.1.1. Increasing debug output
+------------------------------
 
    The files named *dl_* indicate knobs for controlling the debug output
-   of different submodules of the WiMAX stack:
-     *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
-
-       NOTE: Of course, if debugfs is mounted in a directory other than
+   of different submodules of the WiMAX stack::
+
+        # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+        /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+        /sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+
+   NOTE:
+       Of course, if debugfs is mounted in a directory other than
        /sys/kernel/debug, those paths will change.
 
    By reading the file you can obtain the current value of said debug
@@ -74,7 +82,7 @@
    To increase the debug level of, for example, the id-table submodule,
    just write:
 
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+        $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
 
    Increasing numbers yield increasing debug information; for details of
    what is printed and the available levels, check the source. The code
diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst
index e76665a8f2f2..fb5b39f73059 100644
--- a/Documentation/admin-guide/xfs.rst
+++ b/Documentation/admin-guide/xfs.rst
@@ -337,11 +337,12 @@ None at present.
 Removed Sysctls
 ===============
 
+=============================   =======
   Name                          Removed
-  ----                          -------
+=============================   =======
   fs.xfs.xfsbufd_centisec       v4.0
   fs.xfs.age_buffer_centisecs   v4.0
-
+=============================   =======
 
 Error handling
 ==============
diff --git a/Documentation/arm/sa1100/adsbitsy.rst b/Documentation/arm/sa1100/adsbitsy.rst
deleted file mode 100644
index c179cb26b682..000000000000
--- a/Documentation/arm/sa1100/adsbitsy.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-===============================
-ADS Bitsy Single Board Computer
-===============================
-
-(It is different from Bitsy(iPAQ) of Compaq)
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The Linux support for this product has been provided by
-Woojung Huh <whuh@applieddata.net>
-
-Use 'make adsbitsy_config' before any 'make config'.
-This will set up defaults for ADS Bitsy support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0400000.
-
-Linux can  be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- SA1111 USB Master
-- SA1100 serial port
-- pcmcia, compact flash
-- touchscreen(ucb1200)
-- console on LCD screen
-- serial ports (ttyS[0-2])
-  - ttyS0 is default for serial console
-
-To do
-=====
-
-- everything else!  :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions.
-  You should be careful to use flash on board.
-  Its partition is different from GraphicsClient Plus and GraphicsMaster
-
-- 16bpp mode requires a different cable than what ships with the board.
-  Contact ADS or look through the manual to wire your own. Currently,
-  if you compile with 16bit mode support and switch into a lower bpp
-  mode, the timing is off so the image is corrupted.  This will be
-  fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arm/sa1100/assabet.rst
index 3e704831c311..a761e128fb08 100644
--- a/Documentation/arm/sa1100/assabet.rst
+++ b/Documentation/arm/sa1100/assabet.rst
@@ -14,7 +14,7 @@ Building the kernel
 
 To build the kernel with current defaults::
 
-        make assabet_config
+        make assabet_defconfig
         make oldconfig
         make zImage
 
diff --git a/Documentation/arm/sa1100/brutus.rst b/Documentation/arm/sa1100/brutus.rst
deleted file mode 100644
index e1a23bee6d44..000000000000
--- a/Documentation/arm/sa1100/brutus.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-======
-Brutus
-======
-
-Brutus is an evaluation platform for the SA1100 manufactured by Intel.
-For more details, see:
-
-http://developer.intel.com
-
-To compile for Brutus, you must issue the following commands::
-
-        make brutus_config
-        make config
-        [accept all the defaults]
-        make zImage
-
-The resulting kernel will end up in linux/arch/arm/boot/zImage.  This file
-must be loaded at 0xc0008000 in Brutus's memory and execution started at
-0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon
-entry.
-
-But prior to execute the kernel, a ramdisk image must also be loaded in
-memory.  Use memory address 0xd8000000 for this.  Note that the file
-containing the (compressed) ramdisk image must not exceed 4 MB.
-
-Typically, you'll need angelboot to load the kernel.
-The following angelboot.opt file should be used::
-
-        base 0xc0008000
-        entry 0xc0008000
-        r0 0x00000000
-        r1 0x00000010
-        device /dev/ttyS0
-        options "9600 8N1"
-        baud 115200
-        otherfile ramdisk_img.gz
-        otherbase 0xd8000000
-
-Then load the kernel and ramdisk with::
-
-        angelboot -f angelboot.opt zImage
-
-The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your
-host PC) is used by angel to load the kernel and ramdisk image. The serial
-console is provided through the second Brutus serial port. To access it,
-you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow
-control.
-
-Currently supported
-===================
-
-        - RS232 serial ports
-        - audio output
-        - LCD screen
-        - keyboard
-
-The actual Brutus support may not be complete without extra patches.
-If such patches exist, they should be found from
-ftp.netwinder.org/users/n/nico.
-
-A full PCMCIA support is still missing, although it's possible to hack
-some drivers in order to drive already inserted cards at boot time with
-little modifications.
-
-Any contribution is welcome.
-
-Please send patches to nico@fluxnic.net
-
-Have Fun !
diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst
deleted file mode 100644
index 81043d0c6d64..000000000000
--- a/Documentation/arm/sa1100/freebird.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-========
-Freebird
-========
-
-Freebird-1.1 is produced by Legend(C), Inc.
-`http://web.archive.org/web/*/http://www.legend.com.cn`
-and software/linux maintained by Coventive(C), Inc.
-(http://www.coventive.com)
-
-Based on the Nicolas's strongarm kernel tree.
-
-Maintainer:
-
-Chester Kuo
-        - <chester@coventive.com>
-        - <chester@linux.org.tw>
-
-Author:
-
-- Tim wu <timwu@coventive.com>
-- CIH <cih@coventive.com>
-- Eric Peng <ericpeng@coventive.com>
-- Jeff Lee <jeff_lee@coventive.com>
-- Allen Cheng
-- Tony Liu <tonyliu@coventive.com>
diff --git a/Documentation/arm/sa1100/graphicsclient.rst b/Documentation/arm/sa1100/graphicsclient.rst
deleted file mode 100644
index a73d61c3ce91..000000000000
--- a/Documentation/arm/sa1100/graphicsclient.rst
+++ /dev/null
@@ -1,102 +0,0 @@
-=============================================
-ADS GraphicsClient Plus Single Board Computer
-=============================================
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The original Linux support for this product has been provided by
-Nicolas Pitre <nico@fluxnic.net>. Continued development work by
-Woojung Huh <whuh@applieddata.net>
-
-It's currently possible to mount a root filesystem via NFS providing a
-complete Linux environment.  Otherwise a ramdisk image may be used.  The
-board supports MTD/JFFS, so you could also mount something on there.
-
-Use 'make graphicsclient_config' before any 'make config'.  This will set up
-defaults for GraphicsClient Plus support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0200000.
-Also the following registers should have the specified values upon entry::
-
-        r0 = 0
-        r1 = 29 (this is the GraphicsClient architecture number)
-
-Linux can  be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-Angel is not available for the GraphicsClient Plus AFAIK.
-
-There is a  board known as just the GraphicsClient that ADS used to
-produce but has end of lifed. This code will not work on the older
-board with the ADS bootloader, but should still work with Angel,
-as outlined below.  In any case, if you're planning on deploying
-something en masse, you should probably get the newer board.
-
-If using Angel on the older boards, here is a typical angel.opt option file
-if the kernel is loaded through the Angel Debug Monitor::
-
-        base 0xc0200000
-        entry 0xc0200000
-        r0 0x00000000
-        r1 0x0000001d
-        device /dev/ttyS1
-        options "38400 8N1"
-        baud 115200
-        #otherfile ramdisk.gz
-        #otherbase 0xc0800000
-        exec minicom
-
-Then the kernel (and ramdisk if otherfile/otherbase lines above are
-uncommented) would be loaded with::
-
-        angelboot -f angelboot.opt zImage
-
-Here it is assumed that the board is connected to ttyS1 on your PC
-and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow
-control by default.
-
-If any other bootloader is used, ensure it accomplish the same, especially
-for r0/r1 register values before jumping into the kernel.
-
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- on-board SMC 92C96 ethernet NIC
-- SA1100 serial port
-- flash memory access (MTD/JFFS)
-- pcmcia
-- touchscreen(ucb1200)
-- ps/2 keyboard
-- console on LCD screen
-- serial ports (ttyS[0-2])
-  - ttyS0 is default for serial console
-- Smart I/O (ADC, keypad, digital inputs, etc)
-  See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
-  and example user space code. ps/2 keybd is multiplexed through this driver
-
-To do
-=====
-
-- UCB1200 audio with new ucb_generic layer
-- everything else!  :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions.  mtd0 is where
-  the ADS boot ROM and zImage is stored.  It's been marked as
-  read-only to keep you from blasting over the bootloader. :)  mtd1 is
-  for the ramdisk.gz image.  mtd2 is user flash space and can be
-  utilized for either JFFS or if you're feeling crazy, running ext2
-  on top of it. If you're not using the ADS bootloader, you're
-  welcome to blast over the mtd1 partition also.
-
-- 16bpp mode requires a different cable than what ships with the board.
-  Contact ADS or look through the manual to wire your own. Currently,
-  if you compile with 16bit mode support and switch into a lower bpp
-  mode, the timing is off so the image is corrupted.  This will be
-  fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/graphicsmaster.rst b/Documentation/arm/sa1100/graphicsmaster.rst
deleted file mode 100644
index e39892514f0c..000000000000
--- a/Documentation/arm/sa1100/graphicsmaster.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-========================================
-ADS GraphicsMaster Single Board Computer
-========================================
-
-For more details, contact Applied Data Systems or see
-http://www.applieddata.net/products.html
-
-The original Linux support for this product has been provided by
-Nicolas Pitre <nico@fluxnic.net>. Continued development work by
-Woojung Huh <whuh@applieddata.net>
-
-Use 'make graphicsmaster_config' before any 'make config'.
-This will set up defaults for GraphicsMaster support.
-
-The kernel zImage is linked to be loaded and executed at 0xc0400000.
-
-Linux can  be used with the ADS BootLoader that ships with the
-newer rev boards. See their documentation on how to load Linux.
-
-Supported peripherals
-=====================
-
-- SA1100 LCD frame buffer (8/16bpp...sort of)
-- SA1111 USB Master
-- on-board SMC 92C96 ethernet NIC
-- SA1100 serial port
-- flash memory access (MTD/JFFS)
-- pcmcia, compact flash
-- touchscreen(ucb1200)
-- ps/2 keyboard
-- console on LCD screen
-- serial ports (ttyS[0-2])
-  - ttyS0 is default for serial console
-- Smart I/O (ADC, keypad, digital inputs, etc)
-  See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
-  and example user space code. ps/2 keybd is multiplexed through this driver
-
-To do
-=====
-
-- everything else!  :-)
-
-Notes
-=====
-
-- The flash on board is divided into 3 partitions.  mtd0 is where
-  the zImage is stored.  It's been marked as read-only to keep you
-  from blasting over the bootloader. :)  mtd1 is
-  for the ramdisk.gz image.  mtd2 is user flash space and can be
-  utilized for either JFFS or if you're feeling crazy, running ext2
-  on top of it. If you're not using the ADS bootloader, you're
-  welcome to blast over the mtd1 partition also.
-
-- 16bpp mode requires a different cable than what ships with the board.
-  Contact ADS or look through the manual to wire your own. Currently,
-  if you compile with 16bit mode support and switch into a lower bpp
-  mode, the timing is off so the image is corrupted.  This will be
-  fixed soon.
-
-Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
diff --git a/Documentation/arm/sa1100/huw_webpanel.rst b/Documentation/arm/sa1100/huw_webpanel.rst
deleted file mode 100644
index 1dc7ccb165f0..000000000000
--- a/Documentation/arm/sa1100/huw_webpanel.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-=======================
-Hoeft & Wessel Webpanel
-=======================
-
-The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG
-
-If you want more information, please visit
-http://www.hoeft-wessel.de
-
-To build the kernel::
-
-        make huw_webpanel_config
-        make oldconfig
-        [accept all defaults]
-        make zImage
-
-Mostly of the work is done by:
-Roman Jordan         jor@hoeft-wessel.de
-Christoph Schulz    schu@hoeft-wessel.de
-
-2000/12/18/
diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst
index 68c2a280a745..c9aed43280ff 100644
--- a/Documentation/arm/sa1100/index.rst
+++ b/Documentation/arm/sa1100/index.rst
@@ -7,19 +7,7 @@ Intel StrongARM 1100
 .. toctree::
     :maxdepth: 1
 
-    adsbitsy
     assabet
-    brutus
     cerf
-    freebird
-    graphicsclient
-    graphicsmaster
-    huw_webpanel
-    itsy
     lart
-    nanoengine
-    pangolin
-    pleb
     serial_uart
-    tifon
-    yopy
diff --git a/Documentation/arm/sa1100/itsy.rst b/Documentation/arm/sa1100/itsy.rst
deleted file mode 100644
index f49896ba3ef1..000000000000
--- a/Documentation/arm/sa1100/itsy.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-====
-Itsy
-====
-
-Itsy is a research project done by the Western Research Lab, and Systems
-Research Center in Palo Alto, CA. The Itsy project is one of several
-research projects at Compaq that are related to pocket computing.
-
-For more information, see:
-
-        http://www.hpl.hp.com/downloads/crl/itsy/
-
-Notes on initial 2.4 Itsy support (8/27/2000) :
-
-The port was done on an Itsy version 1.5 machine with a daughtercard with
-64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for
-serial console (to see what you're doing).  No other devices have been
-enabled.
-
-To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support.
-Disable Flash and LCD support. and then do a make zImage.
-Finally, you will need to cd to arch/arm/boot/tools and execute a make there
-to build the params-itsy program used to boot the kernel.
-
-In order to install the port of 2.4 to the itsy, You will need to set the
-configuration parameters in the monitor as follows::
-
-        Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
-
-Make sure the start-routine address is set to 0x00060000.
-
-Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the
-flash menu)  Flash the kernel in arch/arm/boot/zImage into 0x08340000
-("p 1 0x00340000").  Finally flash an initial ramdisk into 0xC8000000
-("p 2 0x0")  We used ramdisk-2-30.gz from the 0.11 version directory on
-handhelds.org.
-
-The serial connection we established was at:
-
-8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
-params-itsy program, and in the kernel itself.  This can be changed, but
-not easily. The monitor parameters are easily changed, the params program
-setup is assembly outl's, and the kernel is a configuration item specific to
-the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.)
-
-
-This should get you a properly booting 2.4 kernel on the itsy.
diff --git a/Documentation/arm/sa1100/nanoengine.rst b/Documentation/arm/sa1100/nanoengine.rst
deleted file mode 100644
index 47f1a14cf98a..000000000000
--- a/Documentation/arm/sa1100/nanoengine.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-==========
-nanoEngine
-==========
-
-"nanoEngine" is a SA1110 based single board computer from
-Bright Star Engineering Inc.  See www.brightstareng.com/arm
-for more info.
-(Ref: Stuart Adams <sja@brightstareng.com>)
-
-Also visit Larry Doolittle's "Linux for the nanoEngine" site:
-http://www.brightstareng.com/arm/nanoeng.htm
diff --git a/Documentation/arm/sa1100/pangolin.rst b/Documentation/arm/sa1100/pangolin.rst
deleted file mode 100644
index f0c5c1618553..000000000000
--- a/Documentation/arm/sa1100/pangolin.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-========
-Pangolin
-========
-
-Pangolin is a StrongARM 1110-based evaluation platform produced
-by Dialogue Technology (http://www.dialogue.com.tw/).
-It has EISA slots for ease of configuration with SDRAM/Flash
-memory card, USB/Serial/Audio card, Compact Flash card,
-PCMCIA/IDE card and TFT-LCD card.
-
-To compile for Pangolin, you must issue the following commands::
-
-        make pangolin_config
-        make oldconfig
-        make zImage
-
-Supported peripherals
-=====================
-
-- SA1110 serial port (UART1/UART2/UART3)
-- flash memory access
-- compact flash driver
-- UDA1341 sound driver
-- SA1100 LCD controller for 800x600 16bpp TFT-LCD
-- MQ-200 driver for 800x600 16bpp TFT-LCD
-- Penmount(touch panel) driver
-- PCMCIA driver
-- SMC91C94 LAN driver
-- IDE driver (experimental)
diff --git a/Documentation/arm/sa1100/pleb.rst b/Documentation/arm/sa1100/pleb.rst
deleted file mode 100644
index d5b732967aa3..000000000000
--- a/Documentation/arm/sa1100/pleb.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-====
-PLEB
-====
-
-The PLEB project was started as a student initiative at the School of
-Computer Science and Engineering, University of New South Wales to make a
-pocket computer capable of running the Linux Kernel.
-
-PLEB support has yet to be fully integrated.
-
-For more information, see:
-
-        http://www.cse.unsw.edu.au
diff --git a/Documentation/arm/sa1100/tifon.rst b/Documentation/arm/sa1100/tifon.rst
deleted file mode 100644
index c26e910b9ea7..000000000000
--- a/Documentation/arm/sa1100/tifon.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-=====
-Tifon
-=====
-
-More info has to come...
-
-Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se>
diff --git a/Documentation/arm/sa1100/yopy.rst b/Documentation/arm/sa1100/yopy.rst
deleted file mode 100644
index 5b35a5f61a44..000000000000
--- a/Documentation/arm/sa1100/yopy.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-====
-Yopy
-====
-
-See http://www.yopydeveloper.org for more.
diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst
index 5b8a7f9398d8..ccb951a0bedb 100644
--- a/Documentation/arm/samsung-s3c24xx/index.rst
+++ b/Documentation/arm/samsung-s3c24xx/index.rst
@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==========================
+==========================
 Samsung S3C24XX SoC Family
 ==========================
 
diff --git a/Documentation/arm/sh-mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore
deleted file mode 100644
index c928dbf3cc88..000000000000
--- a/Documentation/arm/sh-mobile/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-vrl4
diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b
deleted file mode 100644
index 12fd51b8de75..000000000000
--- a/Documentation/auxdisplay/cfag12864b
+++ /dev/null
@@ -1,105 +0,0 @@
-        ===================================
-        cfag12864b LCD Driver Documentation
-        ===================================
-
-License:                GPLv2
-Author & Maintainer:    Miguel Ojeda Sandonis
-Date:                   2006-10-27
-
-
-
---------
-0. INDEX
---------
-
-        1. DRIVER INFORMATION
-        2. DEVICE INFORMATION
-        3. WIRING
-        4. USERSPACE PROGRAMMING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports a cfag12864b LCD.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer:   Crystalfontz
-Device Name:    Crystalfontz 12864b LCD Series
-Device Code:    cfag12864b
-Webpage:        http://www.crystalfontz.com
-Device Webpage: http://www.crystalfontz.com/products/12864b/
-Type:           LCD (Liquid Crystal Display)
-Width:          128
-Height:         64
-Colors:         2 (B/N)
-Controller:     ks0108
-Controllers:    2
-Pages:          8 each controller
-Addresses:      64 each page
-Data size:      1 byte each address
-Memory size:    2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
-
-
----------
-3. WIRING
----------
-
-The cfag12864b LCD Series don't have official wiring.
-
-The common wiring is done to the parallel port as shown:
-
-Parallel Port                          cfag12864b
-
-  Name Pin#                            Pin# Name
-
-Strobe ( 1)------------------------------(17) Enable
-Data 0 ( 2)------------------------------( 4) Data 0
-Data 1 ( 3)------------------------------( 5) Data 1
-Data 2 ( 4)------------------------------( 6) Data 2
-Data 3 ( 5)------------------------------( 7) Data 3
-Data 4 ( 6)------------------------------( 8) Data 4
-Data 5 ( 7)------------------------------( 9) Data 5
-Data 6 ( 8)------------------------------(10) Data 6
-Data 7 ( 9)------------------------------(11) Data 7
-       (10)                      [+5v]---( 1) Vdd
-       (11)                      [GND]---( 2) Ground
-       (12)                      [+5v]---(14) Reset
-       (13)                      [GND]---(15) Read / Write
-  Line (14)------------------------------(13) Controller Select 1
-       (15)
-  Init (16)------------------------------(12) Controller Select 2
-Select (17)------------------------------(16) Data / Instruction
-Ground (18)---[GND]              [+5v]---(19) LED +
-Ground (19)---[GND]
-Ground (20)---[GND]              E    A             Values:
-Ground (21)---[GND]       [GND]---[P1]---(18) Vee    - R = Resistor = 22 ohm
-Ground (22)---[GND]                |                 - P1 = Preset = 10 Kohm
-Ground (23)---[GND]       ----   S ------( 3) V0     - P2 = Preset = 1 Kohm
-Ground (24)---[GND]       |  |
-Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
-
-
-------------------------
-4. USERSPACE PROGRAMMING
-------------------------
-
-The cfag12864bfb describes a framebuffer device (/dev/fbX).
-
-It has a size of 1024 bytes = 1 Kbyte.
-Each bit represents one pixel. If the bit is high, the pixel will
-turn on. If the pixel is low, the pixel will turn off.
-
-You can use the framebuffer as a file: fopen, fwrite, fclose...
-Although the LCD won't get updated until the next refresh time arrives.
-
-Also, you can mmap the framebuffer: open & mmap, munmap & close...
-which is the best option for most uses.
-
-Check samples/auxdisplay/cfag12864b-example.c
-for a real working userspace complete program with usage examples.
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108
deleted file mode 100644
index 8ddda0c8ceef..000000000000
--- a/Documentation/auxdisplay/ks0108
+++ /dev/null
@@ -1,55 +0,0 @@
-        ==========================================
-        ks0108 LCD Controller Driver Documentation
-        ==========================================
-
-License:                GPLv2
-Author & Maintainer:    Miguel Ojeda Sandonis
-Date:                   2006-10-27
-
-
-
---------
-0. INDEX
---------
-
-        1. DRIVER INFORMATION
-        2. DEVICE INFORMATION
-        3. WIRING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports the ks0108 LCD controller.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer:   Samsung
-Device Name:    KS0108 LCD Controller
-Device Code:    ks0108
-Webpage:        -
-Device Webpage: -
-Type:           LCD Controller (Liquid Crystal Display Controller)
-Width:          64
-Height:         64
-Colors:         2 (B/N)
-Pages:          8
-Addresses:      64 each page
-Data size:      1 byte each address
-Memory size:    8 * 64 * 1 = 512 bytes
-
-
----------
-3. WIRING
----------
-
-The driver supports data parallel port wiring.
-
-If you aren't building LCD related hardware, you should check
-your LCD specific wiring information in the same folder.
-
-For example, check Documentation/auxdisplay/cfag12864b.
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index da0ed972d224..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
    librs
    genalloc
    errseq
+   packing
    printk-formats
    circular-buffers
    generic-radix-tree
@@ -48,7 +49,7 @@ Interfaces for kernel debugging
    debug-objects
    tracepoint
 
-.. only::  subproject
+.. only:: subproject and html
 
    Indices
    =======
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
 ------------
 
 This API deals with 2 basic operations:
+
   - Packing a CPU-usable number into a memory buffer (with hardware
     constraints/quirks)
   - Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
 
 1. Normally (no quirks), we would do it like this:
 
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7                       6                       5                        4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
-3                       2                       1                        0
+::
+
+  63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+  7                       6                       5                        4
+  31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+  3                       2                       1                        0
 
 That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
 LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
 
 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
 
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7                       6                        5                       4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
-3                       2                        1                       0
+::
+
+  56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+  7                       6                        5                       4
+  24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
+  3                       2                        1                       0
 
 That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
 inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
 
 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
 
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4                       5                       6                       7
-7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0                       1                       2                       3
+::
+
+  39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+  4                       5                       6                       7
+  7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+  0                       1                       2                       3
 
 Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
 byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
    like this:
 
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4                       5                       6                       7
-0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0                       1                       2                       3
+::
+
+  32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+  4                       5                       6                       7
+  0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+  0                       1                       2                       3
 
 
 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
 
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
-3                       2                       1                        0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7                       6                       5                        4
+::
+
+  31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+  3                       2                       1                        0
+  63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+  7                       6                       5                        4
 
 In this case the 8 byte memory region is interpreted as follows: first
 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
    this:
 
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
-3                       2                        1                       0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7                       6                        5                       4
+::
+
+  24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
+  3                       2                        1                       0
+  56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+  7                       6                        5                       4
 
 
 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
    this:
 
-7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0                       1                       2                       3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4                       5                       6                       7
+::
+
+  7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+  0                       1                       2                       3
+  39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+  4                       5                       6                       7
 
 
 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
    are set, it looks like this:
 
-0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0                       1                       2                       3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4                       5                       6                       7
+::
+
+  0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+  0                       1                       2                       3
+  32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+  4                       5                       6                       7
 
 
 We always think of our offsets as if there were no quirk, and we translate
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index c6224d039bcb..ecbebf4ca8e7 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -13,10 +13,10 @@ Integer types
 
         If variable is of Type,         use printk format specifier:
         ------------------------------------------------------------
-                char                    %hhd or %hhx
-                unsigned char           %hhu or %hhx
-                short int               %hd or %hx
-                unsigned short int      %hu or %hx
+                char                    %d or %x
+                unsigned char           %u or %x
+                short int               %d or %x
+                unsigned short int      %u or %x
                 int                     %d or %x
                 unsigned int            %u or %x
                 long                    %ld or %lx
@@ -25,10 +25,10 @@ Integer types
                 unsigned long long      %llu or %llx
                 size_t                  %zu or %zx
                 ssize_t                 %zd or %zx
-                s8                      %hhd or %hhx
-                u8                      %hhu or %hhx
-                s16                     %hd or %hx
-                u16                     %hu or %hx
+                s8                      %d or %x
+                u8                      %u or %x
+                s16                     %d or %x
+                u16                     %u or %x
                 s32                     %d or %x
                 u32                     %u or %x
                 s64                     %lld or %llx
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
index 2907dab56298..8b444b94e92f 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@ Optional properties:
   This means that no unrelated I2C transactions are allowed on the parent I2C
   adapter for the complete multiplexed I2C transaction.
   The properties of mux-locked and parent-locked multiplexers are discussed
-  in more detail in Documentation/i2c/i2c-topology.
+  in more detail in Documentation/i2c/i2c-topology.rst.
 
 For each i2c child node, an I2C child bus will be created. They will
 be numbered based on their order in the device tree.
diff --git a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
index 2ca3d138528e..7ecf6bd60d27 100644
--- a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
+++ b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
@@ -4,7 +4,7 @@ Allwinner SUN8I audio codec
 On Sun8i-A33 SoCs, the audio is separated in different parts:
           - A DAI driver. It uses the "sun4i-i2s" driver which is
           documented here:
-          Documentation/devicetree/bindings/sound/sun4i-i2s.txt
+          Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml
           - An analog part of the codec which is handled as PRCM registers.
           See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
           - An digital part of the codec which is documented in this current
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md
deleted file mode 100644
index dc032db36262..000000000000
--- a/Documentation/devicetree/writing-schema.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# Writing DeviceTree Bindings in json-schema
-
-Devicetree bindings are written using json-schema vocabulary. Schema files are
-written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
-considered more human readable and has some advantages such as allowing
-comments (Prefixed with '#').
-
-## Schema Contents
-
-Each schema doc is a structured json-schema which is defined by a set of
-top-level properties. Generally, there is one binding defined per file. The
-top-level json-schema properties used are:
-
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
-  A property can also define a child DT node with child properties defined
-under it.
-
-  For more details on properties sections, see 'Property Schema' section.
-
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
-
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
-
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
-
-Unless noted otherwise, all properties are required.
-
-## Property Schema
-
-The 'properties' section of the schema contains all the DT properties for a
-binding. Each property contains a set of constraints using json-schema
-vocabulary for that property. The properties schemas are what is used for
-validation of DT files.
-
-For common properties, only additional constraints not covered by the common
-binding schema need to be defined such as how many values are valid or what
-possible values are valid.
-
-Vendor specific properties will typically need more detailed schema. With the
-exception of boolean properties, they should have a reference to a type in
-schemas/types.yaml. A "description" property is always required.
-
-The Devicetree schemas don't exactly match the YAML encoded DT data produced by
-dtc. They are simplified to make them more compact and avoid a bunch of
-boilerplate. The tools process the schema files to produce the final schema for
-validation. There are currently 2 transformations the tools perform.
-
-The default for arrays in json-schema is they are variable sized and allow more
-entries than explicitly defined. This can be restricted by defining 'minItems',
-'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
-size is desired in most cases, so these properties are added based on the
-number of entries in an 'items' list.
-
-The YAML Devicetree format also makes all string values an array and scalar
-values a matrix (in order to define groupings) even when only a single value
-is present. Single entries in schemas are fixed up to match this encoding.
-
-## Testing
-
-### Dependencies
-
-The DT schema project must be installed in order to validate the DT schema
-binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
-
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
-
-dtc must also be built with YAML output support enabled. This requires that
-libyaml and its headers be installed on the host system.
-
-### Running checks
-
-The DT schema binding documents must be validated using the meta-schema (the
-schema for the schema) to ensure they are both valid json-schema and valid
-binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
-
-`make dt_binding_check`
-
-In order to perform validation of DT source files, use the `dtbs_check` target:
-
-`make dtbs_check`
-
-This will first run the `dt_binding_check` which generates the processed schema.
-
-It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
-
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
-
-
-## json-schema Resources
-
-[JSON-Schema Specifications](http://json-schema.org/)
-
-[Using JSON Schema Book](http://usingjsonschema.com/)
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
new file mode 100644
index 000000000000..8f71d1e2ac52
--- /dev/null
+++ b/Documentation/devicetree/writing-schema.rst
@@ -0,0 +1,153 @@
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
+
+Devicetree bindings are written using json-schema vocabulary. Schema files are
+written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
+considered more human readable and has some advantages such as allowing
+comments (Prefixed with '#').
+
+Schema Contents
+---------------
+
+Each schema doc is a structured json-schema which is defined by a set of
+top-level properties. Generally, there is one binding defined per file. The
+top-level json-schema properties used are:
+
+$id
+  A json-schema unique identifier string. The string must be a valid
+  URI typically containing the binding's filename and path. For DT schema, it must
+  begin with "http://devicetree.org/schemas/". The URL is used in constructing
+  references to other files specified in schema "$ref" properties. A $ref values
+  with a leading '/' will have the hostname prepended. A $ref value a relative
+  path or filename only will be prepended with the hostname and path components
+  of the current schema file's '$id' value. A URL is used even for local files,
+  but there may not actually be files present at those locations.
+
+$schema
+  Indicates the meta-schema the schema file adheres to.
+
+title
+  A one line description on the contents of the binding schema.
+
+maintainers
+  A DT specific property. Contains a list of email address(es)
+  for maintainers of this binding.
+
+description
+  Optional. A multi-line text block containing any detailed
+  information about this binding. It should contain things such as what the block
+  or device does, standards the device conforms to, and links to datasheets for
+  more information.
+
+select
+  Optional. A json-schema used to match nodes for applying the
+  schema. By default without 'select', nodes are matched against their possible
+  compatible string values or node name. Most bindings should not need select.
+
+ allOf
+  Optional. A list of other schemas to include. This is used to
+  include other schemas the binding conforms to. This may be schemas for a
+  particular class of devices such as I2C or SPI controllers.
+
+ properties
+  A set of sub-schema defining all the DT properties for the
+  binding. The exact schema syntax depends on whether properties are known,
+  common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
+under it.
+
+For more details on properties sections, see 'Property Schema' section.
+
+patternProperties
+  Optional. Similar to 'properties', but names are regex.
+
+required
+  A list of DT properties from the 'properties' section that
+  must always be present.
+
+examples
+  Optional. A list of one or more DTS hunks implementing the
+  binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+
+Unless noted otherwise, all properties are required.
+
+Property Schema
+---------------
+
+The 'properties' section of the schema contains all the DT properties for a
+binding. Each property contains a set of constraints using json-schema
+vocabulary for that property. The properties schemas are what is used for
+validation of DT files.
+
+For common properties, only additional constraints not covered by the common
+binding schema need to be defined such as how many values are valid or what
+possible values are valid.
+
+Vendor specific properties will typically need more detailed schema. With the
+exception of boolean properties, they should have a reference to a type in
+schemas/types.yaml. A "description" property is always required.
+
+The Devicetree schemas don't exactly match the YAML encoded DT data produced by
+dtc. They are simplified to make them more compact and avoid a bunch of
+boilerplate. The tools process the schema files to produce the final schema for
+validation. There are currently 2 transformations the tools perform.
+
+The default for arrays in json-schema is they are variable sized and allow more
+entries than explicitly defined. This can be restricted by defining 'minItems',
+'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
+size is desired in most cases, so these properties are added based on the
+number of entries in an 'items' list.
+
+The YAML Devicetree format also makes all string values an array and scalar
+values a matrix (in order to define groupings) even when only a single value
+is present. Single entries in schemas are fixed up to match this encoding.
+
+Testing
+-------
+
+Dependencies
+~~~~~~~~~~~~
+
+The DT schema project must be installed in order to validate the DT schema
+binding documents and validate DTS files using the DT schema. The DT schema
+project can be installed with pip::
+
+    pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
+
+dtc must also be built with YAML output support enabled. This requires that
+libyaml and its headers be installed on the host system.
+
+Running checks
+~~~~~~~~~~~~~~
+
+The DT schema binding documents must be validated using the meta-schema (the
+schema for the schema) to ensure they are both valid json-schema and valid
+binding schema. All of the DT binding documents can be validated using the
+``dt_binding_check`` target::
+
+    make dt_binding_check
+
+In order to perform validation of DT source files, use the `dtbs_check` target::
+
+    make dtbs_check
+
+This will first run the `dt_binding_check` which generates the processed schema.
+
+It is also possible to run checks with a single schema file by setting the
+``DT_SCHEMA_FILES`` variable to a specific schema file.
+
+::
+
+    make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
+
+
+json-schema Resources
+---------------------
+
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
 
    pxa_dma
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..38e638abe3eb 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
    dmaengine/index
    slimbus
    soundwire/index
+   thermal/index
    fpga/index
    acpi/index
    backlight/lp855x-driver.rst
@@ -75,6 +76,7 @@ available subsections can be seen below.
    dell_rbu
    edid
    eisa
+   ipmb
    isa
    isapnp
    generic-counter
diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst
index 7e2265144157..3ec3baed84c4 100644
--- a/Documentation/driver-api/ipmb.rst
+++ b/Documentation/driver-api/ipmb.rst
@@ -83,7 +83,7 @@ Instantiate the device
 ----------------------
 
 After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
 If you have multiple BMCs, each connected to your Satellite MC via
 a different I2C bus, you can instantiate a device for each of
 those BMCs.
diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index f5333e3bf486..1f0437676762 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -59,7 +59,7 @@ Part III - How can drivers use the framework?
 
 The main API is spi_nor_scan(). Before you call the hook, a driver should
 initialize the necessary fields for spi_nor{}. Please see
-drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c
+drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
 when you want to write a new driver for a SPI NOR controller.
 Another API is spi_nor_restore(), this is used to restore the status of SPI
 flash chip such as addressing mode. Call it whenever detach the driver from
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
    error_handling
    locking
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
index 645d914c45a6..645d914c45a6 100644
--- a/Documentation/thermal/cpu-cooling-api.rst
+++ b/Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
index 5bd556566c70..5bd556566c70 100644
--- a/Documentation/thermal/exynos_thermal.rst
+++ b/Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
index c21d10838bc5..c21d10838bc5 100644
--- a/Documentation/thermal/exynos_thermal_emulation.rst
+++ b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =======
 Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
index 3f6dfb0b3ea6..3f6dfb0b3ea6 100644
--- a/Documentation/thermal/intel_powerclamp.rst
+++ b/Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
index 37255fd6735d..37255fd6735d 100644
--- a/Documentation/thermal/nouveau_thermal.rst
+++ b/Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
index 67b6a3297238..67b6a3297238 100644
--- a/Documentation/thermal/power_allocator.rst
+++ b/Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
 sustainable_power
         An estimate of the sustained power that can be dissipated by
         the thermal zone. Used by the power allocator governor. For
-        more information see Documentation/thermal/power_allocator.rst
+        more information see Documentation/driver-api/thermal/power_allocator.rst
 
         Unit: milliwatts
 
@@ -563,7 +563,7 @@ k_po
         controller during temperature overshoot. Temperature overshoot
         is when the current temperature is above the "desired
         temperature" trip point. For more information see
-        Documentation/thermal/power_allocator.rst
+        Documentation/driver-api/thermal/power_allocator.rst
 
         RW, Optional
 
@@ -572,7 +572,7 @@ k_pu
         controller during temperature undershoot. Temperature undershoot
         is when the current temperature is below the "desired
         temperature" trip point. For more information see
-        Documentation/thermal/power_allocator.rst
+        Documentation/driver-api/thermal/power_allocator.rst
 
         RW, Optional
 
@@ -580,14 +580,14 @@ k_i
         The integral term of the power allocator governor's PID
         controller. This term allows the PID controller to compensate
         for long term drift. For more information see
-        Documentation/thermal/power_allocator.rst
+        Documentation/driver-api/thermal/power_allocator.rst
 
         RW, Optional
 
 k_d
         The derivative term of the power allocator governor's PID
         controller. For more information see
-        Documentation/thermal/power_allocator.rst
+        Documentation/driver-api/thermal/power_allocator.rst
 
         RW, Optional
 
@@ -598,7 +598,7 @@ integral_cutoff
         example, if integral_cutoff is 0, then the integral term only
         accumulates error when temperature is above the desired
         temperature trip point. For more information see
-        Documentation/thermal/power_allocator.rst
+        Documentation/driver-api/thermal/power_allocator.rst
 
         Unit: millidegree Celsius
 
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
 - trip_point_1_temp
 
 User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
 thermal sys-fs details.
 
 Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt
index c683da198f31..ee922746a64c 100644
--- a/Documentation/features/locking/queued-rwlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt
@@ -30,5 +30,5 @@
     |          um: | TODO |
     |   unicore32: | TODO |
     |         x86: |  ok  |
-    |      xtensa: | TODO |
+    |      xtensa: |  ok  |
     -----------------------
diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt
index e3080b82aefd..c52116c1a049 100644
--- a/Documentation/features/locking/queued-spinlocks/arch-support.txt
+++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt
@@ -9,7 +9,7 @@
     |       alpha: | TODO |
     |         arc: | TODO |
     |         arm: | TODO |
-    |       arm64: | TODO |
+    |       arm64: |  ok  |
     |         c6x: | TODO |
     |        csky: | TODO |
     |       h8300: | TODO |
@@ -30,5 +30,5 @@
     |          um: | TODO |
     |   unicore32: | TODO |
     |         x86: |  ok  |
-    |      xtensa: | TODO |
+    |      xtensa: |  ok  |
     -----------------------
diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt
deleted file mode 100644
index 7521d7500fbe..000000000000
--- a/Documentation/features/locking/rwsem-optimized/arch-support.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-#
-# Feature name:          rwsem-optimized
-#         Kconfig:       !RWSEM_GENERIC_SPINLOCK
-#         description:   arch provides optimized rwsem APIs
-#
-    -----------------------
-    |         arch |status|
-    -----------------------
-    |       alpha: |  ok  |
-    |         arc: | TODO |
-    |         arm: |  ok  |
-    |       arm64: |  ok  |
-    |         c6x: | TODO |
-    |        csky: | TODO |
-    |       h8300: | TODO |
-    |     hexagon: | TODO |
-    |        ia64: |  ok  |
-    |        m68k: | TODO |
-    |  microblaze: | TODO |
-    |        mips: | TODO |
-    |       nds32: | TODO |
-    |       nios2: | TODO |
-    |    openrisc: | TODO |
-    |      parisc: | TODO |
-    |     powerpc: | TODO |
-    |       riscv: | TODO |
-    |        s390: |  ok  |
-    |          sh: |  ok  |
-    |       sparc: |  ok  |
-    |          um: |  ok  |
-    |   unicore32: | TODO |
-    |         x86: |  ok  |
-    |      xtensa: |  ok  |
-    -----------------------
diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt
index 545262c167c3..1711ad48e38a 100644
--- a/Documentation/filesystems/coda.txt
+++ b/Documentation/filesystems/coda.txt
@@ -421,14 +421,14 @@ kernel support.
 
 
   The CodaCred structure defines a variety of user and group ids as
-  they are set for the calling process. The vuid_t and guid_t are 32 bit
+  they are set for the calling process. The vuid_t and vgid_t are 32 bit
   unsigned integers.  It also defines group membership in an array.  On
   Unix the CodaCred has proven sufficient to implement good security
   semantics for Coda but the structure may have to undergo modification
   for the Windows environment when these mature.
 
   struct CodaCred {
-      vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/
+      vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */
       vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */
       vgid_t cr_groups[NGROUPS];        /* Group membership for caller */
   };
diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst
index 4e32cb961e5b..de12016ee419 100644
--- a/Documentation/filesystems/directory-locking
+++ b/Documentation/filesystems/directory-locking.rst
@@ -1,12 +1,17 @@
-        Locking scheme used for directory operations is based on two
+=================
+Directory Locking
+=================
+
+
+Locking scheme used for directory operations is based on two
 kinds of locks - per-inode (->i_rwsem) and per-filesystem
 (->s_vfs_rename_mutex).
 
-        When taking the i_rwsem on multiple non-directory objects, we
+When taking the i_rwsem on multiple non-directory objects, we
 always acquire the locks in order by increasing address.  We'll call
 that "inode pointer" order in the following.
 
-        For our purposes all operations fall in 5 classes:
+For our purposes all operations fall in 5 classes:
 
 1) read access.  Locking rules: caller locks directory we are accessing.
 The lock is taken shared.
@@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange
 case) shared.
 
 5) link creation.  Locking rules:
+
         * lock parent
         * check that source is not a directory
         * lock source
         * call the method.
+
 All locks are exclusive.
 
 6) cross-directory rename.  The trickiest in the whole bunch.  Locking
 rules:
+
         * lock the filesystem
         * lock parents in "ancestors first" order.
         * find source and target.
         * if old parent is equal to or is a descendent of target
-                fail with -ENOTEMPTY
+          fail with -ENOTEMPTY
         * if new parent is equal to or is a descendent of source
-                fail with -ELOOP
+          fail with -ELOOP
         * If it's an exchange, lock both the source and the target.
         * If the target exists, lock it.  If the source is a non-directory,
           lock it.  If we need to lock both, do so in inode pointer order.
         * call the method.
+
 All ->i_rwsem are taken exclusive.  Again, we might get away with locking
 the the source (and target in exchange case) shared.
 
@@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller.
 
 
 If no directory is its own ancestor, the scheme above is deadlock-free.
+
 Proof:
 
         First of all, at any moment we have a partial ordering of the
-objects - A < B iff A is an ancestor of B.
+        objects - A < B iff A is an ancestor of B.
 
         That ordering can change.  However, the following is true:
 
@@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B.
     non-directory object, except renames, which take locks on source and
     target in inode pointer order in the case they are not directories.)
 
-        Now consider the minimal deadlock.  Each process is blocked on
+Now consider the minimal deadlock.  Each process is blocked on
 attempt to acquire some lock and already holds at least one lock.  Let's
 consider the set of contended locks.  First of all, filesystem lock is
 not contended, since any process blocked on it is not holding any locks.
 Thus all processes are blocked on ->i_rwsem.
 
-        By (3), any process holding a non-directory lock can only be
+By (3), any process holding a non-directory lock can only be
 waiting on another non-directory lock with a larger address.  Therefore
 the process holding the "largest" such lock can always make progress, and
 non-directory objects are not included in the set of contended locks.
 
-        Thus link creation can't be a part of deadlock - it can't be
+Thus link creation can't be a part of deadlock - it can't be
 blocked on source and it means that it doesn't hold any locks.
 
-        Any contended object is either held by cross-directory rename or
+Any contended object is either held by cross-directory rename or
 has a child that is also contended.  Indeed, suppose that it is held by
 operation other than cross-directory rename.  Then the lock this operation
 is blocked on belongs to child of that object due to (1).
 
-        It means that one of the operations is cross-directory rename.
+It means that one of the operations is cross-directory rename.
 Otherwise the set of contended objects would be infinite - each of them
 would have a contended child and we had assumed that no object is its
 own descendent.  Moreover, there is exactly one cross-directory rename
 (see above).
 
-        Consider the object blocking the cross-directory rename.  One
+Consider the object blocking the cross-directory rename.  One
 of its descendents is locked by cross-directory rename (otherwise we
 would again have an infinite set of contended objects).  But that
 means that cross-directory rename is taking locks out of order.  Due
@@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor.
 Contradiction.  I.e.  deadlock is impossible.  Q.E.D.
 
 
-        These operations are guaranteed to avoid loop creation.  Indeed,
+These operations are guaranteed to avoid loop creation.  Indeed,
 the only operation that could introduce loops is cross-directory rename.
 Since the only new (parent, child) pair added by rename() is (new parent,
 source), such loop would have to contain these objects and the rest of it
@@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when
 we had acquired filesystem lock and rename() would fail with -ELOOP in that
 case.
 
-        While this locking scheme works for arbitrary DAGs, it relies on
+While this locking scheme works for arbitrary DAGs, it relies on
 ability to check that directory is a descendent of another object.  Current
 implementation assumes that directory graph is a tree.  This assumption is
 also preserved by all operations (cross-directory rename on a tree that would
 not introduce a cycle will leave it a tree and link() fails for directories).
 
-        Notice that "directory" in the above == "anything that might have
+Notice that "directory" in the above == "anything that might have
 children", so if we are going to introduce hybrid objects we will need
 either to make sure that link(2) doesn't work for them or to make changes
 in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2de2fe2ab078..96653ebefd7e 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -20,6 +20,10 @@ algorithms work.
    path-lookup
    api-summary
    splice
+   locking
+   directory-locking
+
+   porting
 
 Filesystem support layers
 =========================
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst
index 204dd3ea36bb..fc3a0704553c 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/locking.rst
@@ -1,14 +1,22 @@
-        The text below describes the locking rules for VFS-related methods.
+=======
+Locking
+=======
+
+The text below describes the locking rules for VFS-related methods.
 It is (believed to be) up-to-date. *Please*, if you change anything in
 prototypes or locking protocols - update this file. And update the relevant
 instances in the tree, don't leave that to maintainers of filesystems/devices/
 etc. At the very least, put the list of dubious cases in the end of this file.
 Don't turn it into log - maintainers of out-of-the-tree code are supposed to
 be able to use diff(1).
-        Thing currently missing here: socket operations. Alexey?
 
---------------------------- dentry_operations --------------------------
-prototypes:
+Thing currently missing here: socket operations. Alexey?
+
+dentry_operations
+=================
+
+prototypes::
+
         int (*d_revalidate)(struct dentry *, unsigned int);
         int (*d_weak_revalidate)(struct dentry *, unsigned int);
         int (*d_hash)(const struct dentry *, struct qstr *);
@@ -24,23 +32,30 @@ prototypes:
         struct dentry *(*d_real)(struct dentry *, const struct inode *);
 
 locking rules:
-                rename_lock     ->d_lock        may block       rcu-walk
-d_revalidate:   no              no              yes (ref-walk)  maybe
-d_weak_revalidate:no            no              yes             no
-d_hash          no              no              no              maybe
-d_compare:      yes             no              no              maybe
-d_delete:       no              yes             no              no
-d_init: no              no              yes             no
-d_release:      no              no              yes             no
-d_prune:        no              yes             no              no
-d_iput:         no              no              yes             no
-d_dname:        no              no              no              no
-d_automount:    no              no              yes             no
-d_manage:       no              no              yes (ref-walk)  maybe
-d_real          no              no              yes             no
-
---------------------------- inode_operations --------------------------- 
-prototypes:
+
+================== ===========  ========        ==============  ========
+ops                rename_lock  ->d_lock        may block       rcu-walk
+================== ===========  ========        ==============  ========
+d_revalidate:      no           no              yes (ref-walk)  maybe
+d_weak_revalidate: no           no              yes             no
+d_hash             no           no              no              maybe
+d_compare:         yes          no              no              maybe
+d_delete:          no           yes             no              no
+d_init:            no           no              yes             no
+d_release:         no           no              yes             no
+d_prune:           no           yes             no              no
+d_iput:            no           no              yes             no
+d_dname:           no           no              no              no
+d_automount:       no           no              yes             no
+d_manage:          no           no              yes (ref-walk)  maybe
+d_real             no           no              yes             no
+================== ===========  ========        ==============  ========
+
+inode_operations
+================
+
+prototypes::
+
         int (*create) (struct inode *,struct dentry *,umode_t, bool);
         struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
         int (*link) (struct dentry *,struct inode *,struct dentry *);
@@ -68,7 +83,10 @@ prototypes:
 
 locking rules:
         all may block
-                i_rwsem(inode)
+
+============    =============================================
+ops             i_rwsem(inode)
+============    =============================================
 lookup:         shared
 create:         exclusive
 link:           exclusive (both)
@@ -89,17 +107,21 @@ fiemap:		no
 update_time:    no
 atomic_open:    exclusive
 tmpfile:        no
+============    =============================================
 
 
         Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
         exclusive on victim.
         cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
 
-See Documentation/filesystems/directory-locking for more detailed discussion
+See Documentation/filesystems/directory-locking.rst for more detailed discussion
 of the locking scheme for directory operations.
 
------------------------ xattr_handler operations -----------------------
-prototypes:
+xattr_handler operations
+========================
+
+prototypes::
+
         bool (*list)(struct dentry *dentry);
         int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
                    struct inode *inode, const char *name, void *buffer,
@@ -110,13 +132,20 @@ prototypes:
 
 locking rules:
         all may block
-                i_rwsem(inode)
+
+=====           ==============
+ops             i_rwsem(inode)
+=====           ==============
 list:           no
 get:            no
 set:            exclusive
+=====           ==============
+
+super_operations
+================
+
+prototypes::
 
---------------------------- super_operations ---------------------------
-prototypes:
         struct inode *(*alloc_inode)(struct super_block *sb);
         void (*free_inode)(struct inode *);
         void (*destroy_inode)(struct inode *);
@@ -138,7 +167,10 @@ prototypes:
 
 locking rules:
         All may block [not true, see below]
-                        s_umount
+
+======================  ============    ========================
+ops                     s_umount        note
+======================  ============    ========================
 alloc_inode:
 free_inode:                             called from RCU callback
 destroy_inode:
@@ -157,6 +189,7 @@ show_options:		no		(namespace_sem)
 quota_read:             no              (see below)
 quota_write:            no              (see below)
 bdev_try_to_free_page:  no              (see below)
+======================  ============    ========================
 
 ->statfs() has s_umount (shared) when called by ustat(2) (native or
 compat), but that's an accident of bad API; s_umount is used to pin
@@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to
 identify the superblock.  Everything else (statfs(), fstatfs(), etc.)
 doesn't hold it when calling ->statfs() - superblock is pinned down
 by resolving the pathname passed to syscall.
+
 ->quota_read() and ->quota_write() functions are both guaranteed to
 be the only ones operating on the quota file by the quota code (via
 dqio_sem) (unless an admin really wants to screw up something and
 writes to quota files with quotas on). For other details about locking
 see also dquot_operations section.
+
 ->bdev_try_to_free_page is called from the ->releasepage handler of
 the block device inode.  See there for more details.
 
---------------------------- file_system_type ---------------------------
-prototypes:
+file_system_type
+================
+
+prototypes::
+
         struct dentry *(*mount) (struct file_system_type *, int,
                        const char *, void *);
         void (*kill_sb) (struct super_block *);
+
 locking rules:
-                may block
+
+=======         =========
+ops             may block
+=======         =========
 mount           yes
 kill_sb         yes
+=======         =========
 
 ->mount() returns ERR_PTR or the root dentry; its superblock should be locked
 on return.
+
 ->kill_sb() takes a write-locked superblock, does all shutdown work on it,
 unlocks and drops the reference.
 
---------------------------- address_space_operations --------------------------
-prototypes:
+address_space_operations
+========================
+prototypes::
+
         int (*writepage)(struct page *page, struct writeback_control *wbc);
         int (*readpage)(struct file *, struct page *);
         int (*writepages)(struct address_space *, struct writeback_control *);
@@ -218,14 +264,16 @@ prototypes:
 locking rules:
         All except set_page_dirty and freepage may block
 
-                        PageLocked(page)        i_rwsem
+======================  ======================== =========
+ops                     PageLocked(page)         i_rwsem
+======================  ======================== =========
 writepage:              yes, unlocks (see below)
 readpage:               yes, unlocks
 writepages:
 set_page_dirty          no
 readpages:
-write_begin:            locks the page          exclusive
-write_end:              yes, unlocks            exclusive
+write_begin:            locks the page           exclusive
+write_end:              yes, unlocks             exclusive
 bmap:
 invalidatepage:         yes
 releasepage:            yes
@@ -239,17 +287,18 @@ is_partially_uptodate:	yes
 error_remove_page:      yes
 swap_activate:          no
 swap_deactivate:        no
+======================  ======================== =========
 
-        ->write_begin(), ->write_end() and ->readpage() may be called from
+->write_begin(), ->write_end() and ->readpage() may be called from
 the request handler (/dev/loop).
 
-        ->readpage() unlocks the page, either synchronously or via I/O
+->readpage() unlocks the page, either synchronously or via I/O
 completion.
 
-        ->readpages() populates the pagecache with the passed pages and starts
+->readpages() populates the pagecache with the passed pages and starts
 I/O against them.  They come unlocked upon I/O completion.
 
-        ->writepage() is used for two purposes: for "memory cleansing" and for
+->writepage() is used for two purposes: for "memory cleansing" and for
 "sync".  These are quite different operations and the behaviour may differ
 depending upon the mode.
 
@@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the
 radix tree.  This incoherency can lead to all sorts of hard-to-debug problems
 in the filesystem like having dirty inodes at umount and losing written data.
 
-        ->writepages() is used for periodic writeback and for syscall-initiated
+->writepages() is used for periodic writeback and for syscall-initiated
 sync operations.  The address_space should start I/O against at least
-*nr_to_write pages.  *nr_to_write must be decremented for each page which is
-written.  The address_space implementation may write more (or less) pages
-than *nr_to_write asks for, but it should try to be reasonably close.  If
-nr_to_write is NULL, all dirty pages must be written.
+``*nr_to_write`` pages.  ``*nr_to_write`` must be decremented for each page
+which is written.  The address_space implementation may write more (or less)
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
+If nr_to_write is NULL, all dirty pages must be written.
 
 writepages should _only_ write pages which are present on
 mapping->io_pages.
 
-        ->set_page_dirty() is called from various places in the kernel
+->set_page_dirty() is called from various places in the kernel
 when the target page is marked as needing writeback.  It may be called
 under spinlock (it cannot block) and is sometimes called with the page
 not locked.
 
-        ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
+->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
 filesystems and by the swapper. The latter will eventually go away.  Please,
 keep it that way and don't breed new callers.
 
-        ->invalidatepage() is called when the filesystem must attempt to drop
+->invalidatepage() is called when the filesystem must attempt to drop
 some or all of the buffers from the page when it is being truncated. It
 returns zero on success. If ->invalidatepage is zero, the kernel uses
 block_invalidatepage() instead.
 
-        ->releasepage() is called when the kernel is about to try to drop the
+->releasepage() is called when the kernel is about to try to drop the
 buffers from the page in preparation for freeing it.  It returns zero to
 indicate that the buffers are (or may be) freeable.  If ->releasepage is zero,
 the kernel assumes that the fs has no private interest in the buffers.
 
-        ->freepage() is called when the kernel is done dropping the page
+->freepage() is called when the kernel is done dropping the page
 from the page cache.
 
-        ->launder_page() may be called prior to releasing a page if
+->launder_page() may be called prior to releasing a page if
 it is still found to be dirty. It returns zero if the page was successfully
 cleaned, or an error value if not. Note that in order to prevent the page
 getting mapped back in and redirtied, it needs to be kept locked
 across the entire operation.
 
-        ->swap_activate will be called with a non-zero argument on
+->swap_activate will be called with a non-zero argument on
 files backing (non block device backed) swapfiles. A return value
 of zero indicates success, in which case this file can be used for
 backing swapspace. The swapspace operations will be proxied to the
 address space operations.
 
-        ->swap_deactivate() will be called in the sys_swapoff()
+->swap_deactivate() will be called in the sys_swapoff()
 path after ->swap_activate() returned success.
 
------------------------ file_lock_operations ------------------------------
-prototypes:
+file_lock_operations
+====================
+
+prototypes::
+
         void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
         void (*fl_release_private)(struct file_lock *);
 
 
 locking rules:
-                        inode->i_lock   may block
+
+===================     =============   =========
+ops                     inode->i_lock   may block
+===================     =============   =========
 fl_copy_lock:           yes             no
-fl_release_private:     maybe           maybe[1]
+fl_release_private:     maybe           maybe[1]_
+===================     =============   =========
+
+.. [1]:
+   ->fl_release_private for flock or POSIX locks is currently allowed
+   to block. Leases however can still be freed while the i_lock is held and
+   so fl_release_private called on a lease should not block.
 
-[1]:    ->fl_release_private for flock or POSIX locks is currently allowed
-to block. Leases however can still be freed while the i_lock is held and
-so fl_release_private called on a lease should not block.
+lock_manager_operations
+=======================
+
+prototypes::
 
------------------------ lock_manager_operations ---------------------------
-prototypes:
         void (*lm_notify)(struct file_lock *);  /* unblock callback */
         int (*lm_grant)(struct file_lock *, struct file_lock *, int);
         void (*lm_break)(struct file_lock *); /* break_lease callback */
@@ -368,24 +428,33 @@ prototypes:
 
 locking rules:
 
-                        inode->i_lock   blocked_lock_lock       may block
+==========              =============   =================       =========
+ops                     inode->i_lock   blocked_lock_lock       may block
+==========              =============   =================       =========
 lm_notify:              yes             yes                     no
 lm_grant:               no              no                      no
 lm_break:               yes             no                      no
 lm_change               yes             no                      no
+==========              =============   =================       =========
+
+buffer_head
+===========
+
+prototypes::
 
---------------------------- buffer_head -----------------------------------
-prototypes:
         void (*b_end_io)(struct buffer_head *bh, int uptodate);
 
 locking rules:
-        called from interrupts. In other words, extreme care is needed here.
+
+called from interrupts. In other words, extreme care is needed here.
 bh is locked, but that's all warranties we have here. Currently only RAID1,
 highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
 call this method upon the IO completion.
 
---------------------------- block_device_operations -----------------------
-prototypes:
+block_device_operations
+=======================
+prototypes::
+
         int (*open) (struct block_device *, fmode_t);
         int (*release) (struct gendisk *, fmode_t);
         int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
@@ -399,7 +468,10 @@ prototypes:
         void (*swap_slot_free_notify) (struct block_device *, unsigned long);
 
 locking rules:
-                        bd_mutex
+
+======================= ===================
+ops                     bd_mutex
+======================= ===================
 open:                   yes
 release:                yes
 ioctl:                  no
@@ -410,6 +482,7 @@ unlock_native_capacity:	no
 revalidate_disk:        no
 getgeo:                 no
 swap_slot_free_notify:  no      (see below)
+======================= ===================
 
 media_changed, unlock_native_capacity and revalidate_disk are called only from
 check_disk_change().
@@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock
 held.
 
 
---------------------------- file_operations -------------------------------
-prototypes:
+file_operations
+===============
+
+prototypes::
+
         loff_t (*llseek) (struct file *, loff_t, int);
         ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
         ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
@@ -455,7 +531,6 @@ prototypes:
                         size_t, unsigned int);
         int (*setlease)(struct file *, long, struct file_lock **, void **);
         long (*fallocate)(struct file *, int, loff_t, loff_t);
-};
 
 locking rules:
         All may block.
@@ -490,8 +565,11 @@ in sys_read() and friends.
 the lease within the individual filesystem to record the result of the
 operation
 
---------------------------- dquot_operations -------------------------------
-prototypes:
+dquot_operations
+================
+
+prototypes::
+
         int (*write_dquot) (struct dquot *);
         int (*acquire_dquot) (struct dquot *);
         int (*release_dquot) (struct dquot *);
@@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations.
 
 What filesystem should expect from the generic quota functions:
 
-                FS recursion    Held locks when called
+==============  ============    =========================
+ops             FS recursion    Held locks when called
+==============  ============    =========================
 write_dquot:    yes             dqonoff_sem or dqptr_sem
 acquire_dquot:  yes             dqonoff_sem or dqptr_sem
 release_dquot:  yes             dqonoff_sem or dqptr_sem
 mark_dirty:     no              -
 write_info:     yes             dqonoff_sem
+==============  ============    =========================
 
 FS recursion means calling ->quota_read() and ->quota_write() from superblock
 operations.
 
 More details about quota locking can be found in fs/dquot.c.
 
---------------------------- vm_operations_struct -----------------------------
-prototypes:
+vm_operations_struct
+====================
+
+prototypes::
+
         void (*open)(struct vm_area_struct*);
         void (*close)(struct vm_area_struct*);
         vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
@@ -525,7 +609,10 @@ prototypes:
         int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
 
 locking rules:
-                mmap_sem        PageLocked(page)
+
+=============   ========        ===========================
+ops             mmap_sem        PageLocked(page)
+=============   ========        ===========================
 open:           yes
 close:          yes
 fault:          yes             can return with page locked
@@ -533,8 +620,9 @@ map_pages:	yes
 page_mkwrite:   yes             can return with page locked
 pfn_mkwrite:    yes
 access:         yes
+=============   ========        ===========================
 
-        ->fault() is called when a previously not present pte is about
+->fault() is called when a previously not present pte is about
 to be faulted in. The filesystem must find and return the page associated
 with the passed in "pgoff" in the vm_fault structure. If it is possible that
 the page may be truncated and/or invalidated, then the filesystem must lock
@@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block
 subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
 locked. The VM will unlock the page.
 
-        ->map_pages() is called when VM asks to map easy accessible pages.
+->map_pages() is called when VM asks to map easy accessible pages.
 Filesystem should find and map pages associated with offsets from "start_pgoff"
 till "end_pgoff". ->map_pages() is called with page table locked and must
 not block.  If it's not possible to reach a page without blocking,
@@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in
 "pte" field in vm_fault structure. Pointers to entries for other offsets
 should be calculated relative to "pte".
 
-        ->page_mkwrite() is called when a previously read-only pte is
+->page_mkwrite() is called when a previously read-only pte is
 about to become writeable. The filesystem again must ensure that there are
 no truncate/invalidate races, and then return with the page locked. If
 the page has been truncated, the filesystem should not look up a new page
 like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
 will cause the VM to retry the fault.
 
-        ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
+->pfn_mkwrite() is the same as page_mkwrite but when the pte is
 VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
 VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
 after this call is to make the pte read-write, unless pfn_mkwrite returns
 an error.
 
-        ->access() is called when get_user_pages() fails in
+->access() is called when get_user_pages() fails in
 access_process_vm(), typically used to debug a process through
 /proc/pid/mem or ptrace.  This function is needed only for
 VM_IO | VM_PFNMAP VMAs.
 
-================================================================================
+--------------------------------------------------------------------------------
+
                         Dubious stuff
 
 (if you break something or notice that it is broken and do not fix it yourself
diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst
index 63889149f532..33d588a01ace 100644
--- a/Documentation/filesystems/nfs/Exporting
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -1,3 +1,4 @@
+:orphan:
 
 Making Filesystems Exportable
 =============================
@@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix
 for the object.  This leads to two related but distinct features of
 the dcache that are not needed for normal filesystem access.
 
-1/ The dcache must sometimes contain objects that are not part of the
+1. The dcache must sometimes contain objects that are not part of the
    proper prefix. i.e that are not connected to the root.
-2/ The dcache must be prepared for a newly found (via ->lookup) directory
+2. The dcache must be prepared for a newly found (via ->lookup) directory
    to already have a (non-connected) dentry, and must be able to move
    that dentry into place (based on the parent and name in the
    ->lookup).   This is particularly needed for directories as
@@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access.
 
 To implement these features, the dcache has:
 
-a/ A dentry flag DCACHE_DISCONNECTED which is set on
+a. A dentry flag DCACHE_DISCONNECTED which is set on
    any dentry that might not be part of the proper prefix.
    This is set when anonymous dentries are created, and cleared when a
    dentry is noticed to be a child of a dentry which is in the proper
@@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on
    dentries.  That guarantees that we won't need to hunt them down upon
    umount.
 
-b/ A primitive for creation of secondary roots - d_obtain_root(inode).
+b. A primitive for creation of secondary roots - d_obtain_root(inode).
    Those do _not_ bear DCACHE_DISCONNECTED.  They are placed on the
    per-superblock list (->s_roots), so they can be located at umount
    time for eviction purposes.
 
-c/ Helper routines to allocate anonymous dentries, and to help attach
+c. Helper routines to allocate anonymous dentries, and to help attach
    loose directory dentries at lookup time. They are:
+
     d_obtain_alias(inode) will return a dentry for the given inode.
       If the inode already has a dentry, one of those is returned.
+
       If it doesn't, a new anonymous (IS_ROOT and
-        DCACHE_DISCONNECTED) dentry is allocated and attached.
+      DCACHE_DISCONNECTED) dentry is allocated and attached.
+
       In the case of a directory, care is taken that only one dentry
       can ever be attached.
+
     d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
       either the passed-in dentry or a preexisting alias for the given inode
       (such as an anonymous one created by d_obtain_alias), if appropriate.
       It returns NULL when the passed-in dentry is used, following the calling
       convention of ->lookup.
- 
+
 Filesystem Issues
 -----------------
 
 For a filesystem to be exportable it must:
- 
-   1/ provide the filehandle fragment routines described below.
-   2/ make sure that d_splice_alias is used rather than d_add
+
+   1. provide the filehandle fragment routines described below.
+   2. make sure that d_splice_alias is used rather than d_add
       when ->lookup finds an inode for a given parent and name.
 
-      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
+      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
 
                 d_add(dentry, inode), NULL
 
       Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
 
-      Typically the ->lookup routine will simply end with a:
+      Typically the ->lookup routine will simply end with a::
 
                 return d_splice_alias(inode, dentry);
         }
 
 
 
-  A file system implementation declares that instances of the filesystem
+A file system implementation declares that instances of the filesystem
 are exportable by setting the s_export_op field in the struct
 super_block.  This field must point to a "struct export_operations"
 struct which has the following members:
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
deleted file mode 100644
index 6b7a41cfcaed..000000000000
--- a/Documentation/filesystems/porting
+++ /dev/null
@@ -1,686 +0,0 @@
-Changes since 2.5.0:
-
----
-[recommended]
-
-New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
-        sb_set_blocksize() and sb_min_blocksize().
-
-Use them.
-
-(sb_find_get_block() replaces 2.4's get_hash_table())
-
----
-[recommended]
-
-New methods: ->alloc_inode() and ->destroy_inode().
-
-Remove inode->u.foo_inode_i
-Declare
-        struct foo_inode_info {
-                /* fs-private stuff */
-                struct inode vfs_inode;
-        };
-        static inline struct foo_inode_info *FOO_I(struct inode *inode)
-        {
-                return list_entry(inode, struct foo_inode_info, vfs_inode);
-        }
-
-Use FOO_I(inode) instead of &inode->u.foo_inode_i;
-
-Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
-foo_inode_info and return the address of ->vfs_inode, the latter should free
-FOO_I(inode) (see in-tree filesystems for examples).
-
-Make them ->alloc_inode and ->destroy_inode in your super_operations.
-
-Keep in mind that now you need explicit initialization of private data
-typically between calling iget_locked() and unlocking the inode.
-
-At some point that will become mandatory.
-
----
-[mandatory]
-
-Change of file_system_type method (->read_super to ->get_sb)
-
-->read_super() is no more.  Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
-
-Turn your foo_read_super() into a function that would return 0 in case of
-success and negative number in case of error (-EINVAL unless you have more
-informative error value to report).  Call it foo_fill_super().  Now declare
-
-int foo_get_sb(struct file_system_type *fs_type,
-        int flags, const char *dev_name, void *data, struct vfsmount *mnt)
-{
-        return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
-                           mnt);
-}
-
-(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
-filesystem).
-
-Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
-foo_get_sb.
-
----
-[mandatory]
-
-Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
-Most likely there is no need to change anything, but if you relied on
-global exclusion between renames for some internal purpose - you need to
-change your internal locking.  Otherwise exclusion warranties remain the
-same (i.e. parents and victim are locked, etc.).
-
----
-[informational]
-
-Now we have the exclusion between ->lookup() and directory removal (by
-->rmdir() and ->rename()).  If you used to need that exclusion and do
-it by internal locking (most of filesystems couldn't care less) - you
-can relax your locking.
-
----
-[mandatory]
-
-->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
-->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
-and ->readdir() are called without BKL now.  Grab it on entry, drop upon return
-- that will guarantee the same locking you used to have.  If your method or its
-parts do not need BKL - better yet, now you can shift lock_kernel() and
-unlock_kernel() so that they would protect exactly what needs to be
-protected.
-
----
-[mandatory]
-
-BKL is also moved from around sb operations. BKL should have been shifted into
-individual fs sb_op functions.  If you don't need it, remove it.
-
----
-[informational]
-
-check for ->link() target not being a directory is done by callers.  Feel
-free to drop it...
-
----
-[informational]
-
-->link() callers hold ->i_mutex on the object we are linking to.  Some of your
-problems might be over...
-
----
-[mandatory]
-
-new file_system_type method - kill_sb(superblock).  If you are converting
-an existing filesystem, set it according to ->fs_flags:
-        FS_REQUIRES_DEV         -       kill_block_super
-        FS_LITTER               -       kill_litter_super
-        neither                 -       kill_anon_super
-FS_LITTER is gone - just remove it from fs_flags.
-
----
-[mandatory]
-
-        FS_SINGLE is gone (actually, that had happened back when ->get_sb()
-went in - and hadn't been documented ;-/).  Just remove it from fs_flags
-(and see ->get_sb() entry for other actions).
-
----
-[mandatory]
-
-->setattr() is called without BKL now.  Caller _always_ holds ->i_mutex, so
-watch for ->i_mutex-grabbing code that might be used by your ->setattr().
-Callers of notify_change() need ->i_mutex now.
-
----
-[recommended]
-
-New super_block field "struct export_operations *s_export_op" for
-explicit support for exporting, e.g. via NFS.  The structure is fully
-documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
-
-Briefly it allows for the definition of decode_fh and encode_fh operations
-to encode and decode filehandles, and allows the filesystem to use
-a standard helper function for decode_fh, and provide file-system specific
-support for this helper, particularly get_parent.
-
-It is planned that this will be required for exporting once the code
-settles down a bit.
-
-[mandatory]
-
-s_export_op is now required for exporting a filesystem.
-isofs, ext2, ext3, resierfs, fat
-can be used as examples of very different filesystems.
-
----
-[mandatory]
-
-iget4() and the read_inode2 callback have been superseded by iget5_locked()
-which has the following prototype,
-
-    struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
-                                int (*test)(struct inode *, void *),
-                                int (*set)(struct inode *, void *),
-                                void *data);
-
-'test' is an additional function that can be used when the inode
-number is not sufficient to identify the actual file object. 'set'
-should be a non-blocking function that initializes those parts of a
-newly created inode to allow the test function to succeed. 'data' is
-passed as an opaque value to both test and set functions.
-
-When the inode has been created by iget5_locked(), it will be returned with the
-I_NEW flag set and will still be locked.  The filesystem then needs to finalize
-the initialization. Once the inode is initialized it must be unlocked by
-calling unlock_new_inode().
-
-The filesystem is responsible for setting (and possibly testing) i_ino
-when appropriate. There is also a simpler iget_locked function that
-just takes the superblock and inode number as arguments and does the
-test and set for you.
-
-e.g.
-        inode = iget_locked(sb, ino);
-        if (inode->i_state & I_NEW) {
-                err = read_inode_from_disk(inode);
-                if (err < 0) {
-                        iget_failed(inode);
-                        return err;
-                }
-                unlock_new_inode(inode);
-        }
-
-Note that if the process of setting up a new inode fails, then iget_failed()
-should be called on the inode to render it dead, and an appropriate error
-should be passed back to the caller.
-
----
-[recommended]
-
-->getattr() finally getting used.  See instances in nfs, minix, etc.
-
----
-[mandatory]
-
-->revalidate() is gone.  If your filesystem had it - provide ->getattr()
-and let it call whatever you had as ->revlidate() + (for symlinks that
-had ->revalidate()) add calls in ->follow_link()/->readlink().
-
----
-[mandatory]
-
-->d_parent changes are not protected by BKL anymore.  Read access is safe
-if at least one of the following is true:
-        * filesystem has no cross-directory rename()
-        * we know that parent had been locked (e.g. we are looking at
-->d_parent of ->lookup() argument).
-        * we are called from ->rename().
-        * the child's ->d_lock is held
-Audit your code and add locking if needed.  Notice that any place that is
-not protected by the conditions above is risky even in the old tree - you
-had been relying on BKL and that's prone to screwups.  Old tree had quite
-a few holes of that kind - unprotected access to ->d_parent leading to
-anything from oops to silent memory corruption.
-
----
-[mandatory]
-
-        FS_NOMOUNT is gone.  If you use it - just set SB_NOUSER in flags
-(see rootfs for one kind of solution and bdev/socket/pipe for another).
-
----
-[recommended]
-
-        Use bdev_read_only(bdev) instead of is_read_only(kdev).  The latter
-is still alive, but only because of the mess in drivers/s390/block/dasd.c.
-As soon as it gets fixed is_read_only() will die.
-
----
-[mandatory]
-
-->permission() is called without BKL now. Grab it on entry, drop upon
-return - that will guarantee the same locking you used to have.  If
-your method or its parts do not need BKL - better yet, now you can
-shift lock_kernel() and unlock_kernel() so that they would protect
-exactly what needs to be protected.
-
----
-[mandatory]
-
-->statfs() is now called without BKL held.  BKL should have been
-shifted into individual fs sb_op functions where it's not clear that
-it's safe to remove it.  If you don't need it, remove it.
-
----
-[mandatory]
-
-        is_read_only() is gone; use bdev_read_only() instead.
-
----
-[mandatory]
-
-        destroy_buffers() is gone; use invalidate_bdev().
-
----
-[mandatory]
-
-        fsync_dev() is gone; use fsync_bdev().  NOTE: lvm breakage is
-deliberate; as soon as struct block_device * is propagated in a reasonable
-way by that code fixing will become trivial; until then nothing can be
-done.
-
-[mandatory]
-
-        block truncatation on error exit from ->write_begin, and ->direct_IO
-moved from generic methods (block_write_begin, cont_write_begin,
-nobh_write_begin, blockdev_direct_IO*) to callers.  Take a look at
-ext2_write_failed and callers for an example.
-
-[mandatory]
-
-        ->truncate is gone.  The whole truncate sequence needs to be
-implemented in ->setattr, which is now mandatory for filesystems
-implementing on-disk size changes.  Start with a copy of the old inode_setattr
-and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
-be in order of zeroing blocks using block_truncate_page or similar helpers,
-size update and on finally on-disk truncation which should not fail.
-setattr_prepare (which used to be inode_change_ok) now includes the size checks
-for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
-
-[mandatory]
-
-        ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
-be used instead.  It gets called whenever the inode is evicted, whether it has
-remaining links or not.  Caller does *not* evict the pagecache or inode-associated
-metadata buffers; the method has to use truncate_inode_pages_final() to get rid
-of those. Caller makes sure async writeback cannot be running for the inode while
-(or after) ->evict_inode() is called.
-
-        ->drop_inode() returns int now; it's called on final iput() with
-inode->i_lock held and it returns true if filesystems wants the inode to be
-dropped.  As before, generic_drop_inode() is still the default and it's been
-updated appropriately.  generic_delete_inode() is also alive and it consists
-simply of return 1.  Note that all actual eviction work is done by caller after
-->drop_inode() returns.
-
-        As before, clear_inode() must be called exactly once on each call of
-->evict_inode() (as it used to be for each call of ->delete_inode()).  Unlike
-before, if you are using inode-associated metadata buffers (i.e.
-mark_buffer_dirty_inode()), it's your responsibility to call
-invalidate_inode_buffers() before clear_inode().
-
-        NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
-if it's zero is not *and* *never* *had* *been* enough.  Final unlink() and iput()
-may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
-free the on-disk inode, you may end up doing that while ->write_inode() is writing
-to it.
-
----
-[mandatory]
-
-        .d_delete() now only advises the dcache as to whether or not to cache
-unreferenced dentries, and is now only called when the dentry refcount goes to
-0. Even on 0 refcount transition, it must be able to tolerate being called 0,
-1, or more times (eg. constant, idempotent).
-
----
-[mandatory]
-
-        .d_compare() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
-
-        .d_hash() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
-        dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
-for details of what locks to replace dcache_lock with in order to protect
-particular things. Most of the time, a filesystem only needs ->d_lock, which
-protects *all* the dcache state of a given dentry.
-
---
-[mandatory]
-
-        Filesystems must RCU-free their inodes, if they can have been accessed
-via rcu-walk path walk (basically, if the file can have had a path name in the
-vfs namespace).
-
-        Even though i_dentry and i_rcu share storage in a union, we will
-initialize the former in inode_init_always(), so just leave it alone in
-the callback.  It used to be necessary to clean it there, but not anymore
-(starting at 3.2).
-
---
-[recommended]
-        vfs now tries to do path walking in "rcu-walk mode", which avoids
-atomic operations and scalability hazards on dentries and inodes (see
-Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
-(above) are examples of the changes required to support this. For more complex
-filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
-no changes are required to the filesystem. However, this is costly and loses
-the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
-are rcu-walk aware, shown below. Filesystems should take advantage of this
-where possible.
-
---
-[mandatory]
-        d_revalidate is a callback that is made on every path element (if
-the filesystem provides it), which requires dropping out of rcu-walk mode. This
-may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
-returned if the filesystem cannot handle rcu-walk. See
-Documentation/filesystems/vfs.rst for more details.
-
-        permission is an inode permission check that is called on many or all
-directory inodes on the way down a path walk (to check for exec permission). It
-must now be rcu-walk aware (mask & MAY_NOT_BLOCK).  See
-Documentation/filesystems/vfs.rst for more details.
- 
---
-[mandatory]
-        In ->fallocate() you must check the mode option passed in.  If your
-filesystem does not support hole punching (deallocating space in the middle of a
-file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
-Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
-so the i_size should not change when hole punching, even when puching the end of
-a file off.
-
---
-[mandatory]
-        ->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
-a matter of switching from calling get_sb_... to mount_... and changing the
-function type.  If you were doing it manually, just switch from setting ->mnt_root
-to some pointer to returning that pointer.  On errors return ERR_PTR(...).
-
---
-[mandatory]
-        ->permission() and generic_permission()have lost flags
-argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
-        generic_permission() has also lost the check_acl argument; ACL checking
-has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
-to read an ACL from disk.
-
---
-[mandatory]
-        If you implement your own ->llseek() you must handle SEEK_HOLE and
-SEEK_DATA.  You can hanle this by returning -EINVAL, but it would be nicer to
-support it in some way.  The generic handler assumes that the entire file is
-data and there is a virtual hole at the end of the file.  So if the provided
-offset is less than i_size and SEEK_DATA is specified, return the same offset.
-If the above is true for the offset and you are given SEEK_HOLE, return the end
-of the file.  If the offset is i_size or greater return -ENXIO in either case.
-
-[mandatory]
-        If you have your own ->fsync() you must make sure to call
-filemap_write_and_wait_range() so that all dirty pages are synced out properly.
-You must also keep in mind that ->fsync() is not called with i_mutex held
-anymore, so if you require i_mutex locking you must make sure to take it and
-release it yourself.
-
---
-[mandatory]
-        d_alloc_root() is gone, along with a lot of bugs caused by code
-misusing it.  Replacement: d_make_root(inode).  On success d_make_root(inode)
-allocates and returns a new dentry instantiated with the passed in inode.
-On failure NULL is returned and the passed in inode is dropped so the reference
-to inode is consumed in all cases and failure handling need not do any cleanup
-for the inode.  If d_make_root(inode) is passed a NULL inode it returns NULL
-and also requires no further error handling. Typical usage is:
-
-        inode = foofs_new_inode(....);
-        s->s_root = d_make_root(inode);
-        if (!s->s_root)
-                /* Nothing needed for the inode cleanup */
-                return -ENOMEM;
-        ...
-
---
-[mandatory]
-        The witch is dead!  Well, 2/3 of it, anyway.  ->d_revalidate() and
-->lookup() do *not* take struct nameidata anymore; just the flags.
---
-[mandatory]
-        ->create() doesn't take struct nameidata *; unlike the previous
-two, it gets "is it an O_EXCL or equivalent?" boolean argument.  Note that
-local filesystems can ignore tha argument - they are guaranteed that the
-object doesn't exist.  It's remote/distributed ones that might care...
---
-[mandatory]
-        FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
-in your dentry operations instead.
---
-[mandatory]
-        vfs_readdir() is gone; switch to iterate_dir() instead
---
-[mandatory]
-        ->readdir() is gone now; switch to ->iterate()
-[mandatory]
-        vfs_follow_link has been removed.  Filesystems must use nd_set_link
-        from ->follow_link for normal symlinks, or nd_jump_link for magic
-        /proc/<pid> style links.
---
-[mandatory]
-        iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
-        called with both ->i_lock and inode_hash_lock held; the former is *not*
-        taken anymore, so verify that your callbacks do not rely on it (none
-        of the in-tree instances did).  inode_hash_lock is still held,
-        of course, so they are still serialized wrt removal from inode hash,
-        as well as wrt set() callback of iget5_locked().
---
-[mandatory]
-        d_materialise_unique() is gone; d_splice_alias() does everything you
-        need now.  Remember that they have opposite orders of arguments ;-/
---
-[mandatory]
-        f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
-        it entirely.
---
-[mandatory]
-        never call ->read() and ->write() directly; use __vfs_{read,write} or
-        wrappers; instead of checking for ->write or ->read being NULL, look for
-        FMODE_CAN_{WRITE,READ} in file->f_mode.
---
-[mandatory]
-        do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
-        instead.
---
-[mandatory]
-        ->aio_read/->aio_write are gone.  Use ->read_iter/->write_iter.
----
-[recommended]
-        for embedded ("fast") symlinks just set inode->i_link to wherever the
-        symlink body is and use simple_follow_link() as ->follow_link().
---
-[mandatory]
-        calling conventions for ->follow_link() have changed.  Instead of returning
-        cookie and using nd_set_link() to store the body to traverse, we return
-        the body to traverse and store the cookie using explicit void ** argument.
-        nameidata isn't passed at all - nd_jump_link() doesn't need it and
-        nd_[gs]et_link() is gone.
---
-[mandatory]
-        calling conventions for ->put_link() have changed.  It gets inode instead of
-        dentry,  it does not get nameidata at all and it gets called only when cookie
-        is non-NULL.  Note that link body isn't available anymore, so if you need it,
-        store it as cookie.
---
-[mandatory]
-        any symlink that might use page_follow_link_light/page_put_link() must
-        have inode_nohighmem(inode) called before anything might start playing with
-        its pagecache.  No highmem pages should end up in the pagecache of such
-        symlinks.  That includes any preseeding that might be done during symlink
-        creation.  __page_symlink() will honour the mapping gfp flags, so once
-        you've done inode_nohighmem() it's safe to use, but if you allocate and
-        insert the page manually, make sure to use the right gfp flags.
---
-[mandatory]
-        ->follow_link() is replaced with ->get_link(); same API, except that
-                * ->get_link() gets inode as a separate argument
-                * ->get_link() may be called in RCU mode - in that case NULL
-                  dentry is passed
---
-[mandatory]
-        ->get_link() gets struct delayed_call *done now, and should do
-        set_delayed_call() where it used to set *cookie.
-        ->put_link() is gone - just give the destructor to set_delayed_call()
-        in ->get_link().
---
-[mandatory]
-        ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
-        dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
-        in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
-        called before we attach dentry to inode.
---
-[mandatory]
-        symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
-        i_pipe/i_link union zeroed out at inode eviction.  As the result, you can't
-        assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
-        it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
-        to fix shmem_destroy_callback() that used to take that kind of shortcut;
-        watch out, since that shortcut is no longer valid.
---
-[mandatory]
-        ->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
-        they used to - they just take it exclusive.  However, ->lookup() may be
-        called with parent locked shared.  Its instances must not
-                * use d_instantiate) and d_rehash() separately - use d_add() or
-                  d_splice_alias() instead.
-                * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
-                * in the unlikely case when (read-only) access to filesystem
-                  data structures needs exclusion for some reason, arrange it
-                  yourself.  None of the in-tree filesystems needed that.
-                * rely on ->d_parent and ->d_name not changing after dentry has
-                  been fed to d_add() or d_splice_alias().  Again, none of the
-                  in-tree instances relied upon that.
-        We are guaranteed that lookups of the same name in the same directory
-        will not happen in parallel ("same" in the sense of your ->d_compare()).
-        Lookups on different names in the same directory can and do happen in
-        parallel now.
---
-[recommended]
-        ->iterate_shared() is added; it's a parallel variant of ->iterate().
-        Exclusion on struct file level is still provided (as well as that
-        between it and lseek on the same struct file), but if your directory
-        has been opened several times, you can get these called in parallel.
-        Exclusion between that method and all directory-modifying ones is
-        still provided, of course.
-
-        Often enough ->iterate() can serve as ->iterate_shared() without any
-        changes - it is a read-only operation, after all.  If you have any
-        per-inode or per-dentry in-core data structures modified by ->iterate(),
-        you might need something to serialize the access to them.  If you
-        do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
-        that; look for in-tree examples.
-
-        Old method is only used if the new one is absent; eventually it will
-        be removed.  Switch while you still can; the old one won't stay.
---
-[mandatory]
-        ->atomic_open() calls without O_CREAT may happen in parallel.
---
-[mandatory]
-        ->setxattr() and xattr_handler.set() get dentry and inode passed separately.
-        dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
-        in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
-        called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
-        ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
-[mandatory]
-        ->d_compare() doesn't get parent as a separate argument anymore.  If you
-        used it for finding the struct super_block involved, dentry->d_sb will
-        work just as well; if it's something more complicated, use dentry->d_parent.
-        Just be careful not to assume that fetching it more than once will yield
-        the same value - in RCU mode it could change under you.
---
-[mandatory]
-        ->rename() has an added flags argument.  Any flags not handled by the
-        filesystem should result in EINVAL being returned.
---
-[recommended]
-        ->readlink is optional for symlinks.  Don't set, unless filesystem needs
-        to fake something for readlink(2).
---
-[mandatory]
-        ->getattr() is now passed a struct path rather than a vfsmount and
-        dentry separately, and it now has request_mask and query_flags arguments
-        to specify the fields and sync type requested by statx.  Filesystems not
-        supporting any statx-specific features may ignore the new arguments.
---
-[mandatory]
-        ->atomic_open() calling conventions have changed.  Gone is int *opened,
-        along with FILE_OPENED/FILE_CREATED.  In place of those we have
-        FMODE_OPENED/FMODE_CREATED, set in file->f_mode.  Additionally, return
-        value for 'called finish_no_open(), open it yourself' case has become
-        0, not 1.  Since finish_no_open() itself is returning 0 now, that part
-        does not need any changes in ->atomic_open() instances.
---
-[mandatory]
-        alloc_file() has become static now; two wrappers are to be used instead.
-        alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
-        when dentry needs to be created; that's the majority of old alloc_file()
-        users.  Calling conventions: on success a reference to new struct file
-        is returned and callers reference to inode is subsumed by that.  On
-        failure, ERR_PTR() is returned and no caller's references are affected,
-        so the caller needs to drop the inode reference it held.
-        alloc_file_clone(file, flags, ops) does not affect any caller's references.
-        On success you get a new struct file sharing the mount/dentry with the
-        original, on failure - ERR_PTR().
---
-[mandatory]
-        ->clone_file_range() and ->dedupe_file_range have been replaced with
-        ->remap_file_range().  See Documentation/filesystems/vfs.rst for more
-        information.
---
-[recommended]
-        ->lookup() instances doing an equivalent of
-                if (IS_ERR(inode))
-                        return ERR_CAST(inode);
-                return d_splice_alias(inode, dentry);
-        don't need to bother with the check - d_splice_alias() will do the
-        right thing when given ERR_PTR(...) as inode.  Moreover, passing NULL
-        inode to d_splice_alias() will also do the right thing (equivalent of
-        d_add(dentry, NULL); return NULL;), so that kind of special cases
-        also doesn't need a separate treatment.
---
-[strongly recommended]
-        take the RCU-delayed parts of ->destroy_inode() into a new method -
-        ->free_inode().  If ->destroy_inode() becomes empty - all the better,
-        just get rid of it.  Synchronous work (e.g. the stuff that can't
-        be done from an RCU callback, or any WARN_ON() where we want the
-        stack trace) *might* be movable to ->evict_inode(); however,
-        that goes only for the things that are not needed to balance something
-        done by ->alloc_inode().  IOW, if it's cleaning up the stuff that
-        might have accumulated over the life of in-core inode, ->evict_inode()
-        might be a fit.
-
-        Rules for inode destruction:
-                * if ->destroy_inode() is non-NULL, it gets called
-                * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
-                * combination of NULL ->destroy_inode and NULL ->free_inode is
-                  treated as NULL/free_inode_nonrcu, to preserve the compatibility.
-
-        Note that the callback (be it via ->free_inode() or explicit call_rcu()
-        in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
-        as the matter of fact, the superblock and all associated structures
-        might be already gone.  The filesystem driver is guaranteed to be still
-        there, but that's it.  Freeing memory in the callback is fine; doing
-        more than that is possible, but requires a lot of care and is best
-        avoided.
---
-[mandatory]
-        DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
-        default.  DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
-        business doing so.
---
-[mandatory]
-        d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
-        very suspect (and won't work in modules).  Such uses are very likely to
-        be misspelled d_alloc_anon().
diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst
new file mode 100644
index 000000000000..f18506083ced
--- /dev/null
+++ b/Documentation/filesystems/porting.rst
@@ -0,0 +1,852 @@
+====================
+Changes since 2.5.0:
+====================
+
+---
+
+**recommended**
+
+New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
+sb_set_blocksize() and sb_min_blocksize().
+
+Use them.
+
+(sb_find_get_block() replaces 2.4's get_hash_table())
+
+---
+
+**recommended**
+
+New methods: ->alloc_inode() and ->destroy_inode().
+
+Remove inode->u.foo_inode_i
+
+Declare::
+
+        struct foo_inode_info {
+                /* fs-private stuff */
+                struct inode vfs_inode;
+        };
+        static inline struct foo_inode_info *FOO_I(struct inode *inode)
+        {
+                return list_entry(inode, struct foo_inode_info, vfs_inode);
+        }
+
+Use FOO_I(inode) instead of &inode->u.foo_inode_i;
+
+Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
+foo_inode_info and return the address of ->vfs_inode, the latter should free
+FOO_I(inode) (see in-tree filesystems for examples).
+
+Make them ->alloc_inode and ->destroy_inode in your super_operations.
+
+Keep in mind that now you need explicit initialization of private data
+typically between calling iget_locked() and unlocking the inode.
+
+At some point that will become mandatory.
+
+---
+
+**mandatory**
+
+Change of file_system_type method (->read_super to ->get_sb)
+
+->read_super() is no more.  Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
+
+Turn your foo_read_super() into a function that would return 0 in case of
+success and negative number in case of error (-EINVAL unless you have more
+informative error value to report).  Call it foo_fill_super().  Now declare::
+
+  int foo_get_sb(struct file_system_type *fs_type,
+        int flags, const char *dev_name, void *data, struct vfsmount *mnt)
+  {
+        return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
+                           mnt);
+  }
+
+(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
+filesystem).
+
+Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
+foo_get_sb.
+
+---
+
+**mandatory**
+
+Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
+Most likely there is no need to change anything, but if you relied on
+global exclusion between renames for some internal purpose - you need to
+change your internal locking.  Otherwise exclusion warranties remain the
+same (i.e. parents and victim are locked, etc.).
+
+---
+
+**informational**
+
+Now we have the exclusion between ->lookup() and directory removal (by
+->rmdir() and ->rename()).  If you used to need that exclusion and do
+it by internal locking (most of filesystems couldn't care less) - you
+can relax your locking.
+
+---
+
+**mandatory**
+
+->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
+->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
+and ->readdir() are called without BKL now.  Grab it on entry, drop upon return
+- that will guarantee the same locking you used to have.  If your method or its
+parts do not need BKL - better yet, now you can shift lock_kernel() and
+unlock_kernel() so that they would protect exactly what needs to be
+protected.
+
+---
+
+**mandatory**
+
+BKL is also moved from around sb operations. BKL should have been shifted into
+individual fs sb_op functions.  If you don't need it, remove it.
+
+---
+
+**informational**
+
+check for ->link() target not being a directory is done by callers.  Feel
+free to drop it...
+
+---
+
+**informational**
+
+->link() callers hold ->i_mutex on the object we are linking to.  Some of your
+problems might be over...
+
+---
+
+**mandatory**
+
+new file_system_type method - kill_sb(superblock).  If you are converting
+an existing filesystem, set it according to ->fs_flags::
+
+        FS_REQUIRES_DEV         -       kill_block_super
+        FS_LITTER               -       kill_litter_super
+        neither                 -       kill_anon_super
+
+FS_LITTER is gone - just remove it from fs_flags.
+
+---
+
+**mandatory**
+
+FS_SINGLE is gone (actually, that had happened back when ->get_sb()
+went in - and hadn't been documented ;-/).  Just remove it from fs_flags
+(and see ->get_sb() entry for other actions).
+
+---
+
+**mandatory**
+
+->setattr() is called without BKL now.  Caller _always_ holds ->i_mutex, so
+watch for ->i_mutex-grabbing code that might be used by your ->setattr().
+Callers of notify_change() need ->i_mutex now.
+
+---
+
+**recommended**
+
+New super_block field ``struct export_operations *s_export_op`` for
+explicit support for exporting, e.g. via NFS.  The structure is fully
+documented at its declaration in include/linux/fs.h, and in
+Documentation/filesystems/nfs/exporting.rst.
+
+Briefly it allows for the definition of decode_fh and encode_fh operations
+to encode and decode filehandles, and allows the filesystem to use
+a standard helper function for decode_fh, and provide file-system specific
+support for this helper, particularly get_parent.
+
+It is planned that this will be required for exporting once the code
+settles down a bit.
+
+**mandatory**
+
+s_export_op is now required for exporting a filesystem.
+isofs, ext2, ext3, resierfs, fat
+can be used as examples of very different filesystems.
+
+---
+
+**mandatory**
+
+iget4() and the read_inode2 callback have been superseded by iget5_locked()
+which has the following prototype::
+
+    struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
+                                int (*test)(struct inode *, void *),
+                                int (*set)(struct inode *, void *),
+                                void *data);
+
+'test' is an additional function that can be used when the inode
+number is not sufficient to identify the actual file object. 'set'
+should be a non-blocking function that initializes those parts of a
+newly created inode to allow the test function to succeed. 'data' is
+passed as an opaque value to both test and set functions.
+
+When the inode has been created by iget5_locked(), it will be returned with the
+I_NEW flag set and will still be locked.  The filesystem then needs to finalize
+the initialization. Once the inode is initialized it must be unlocked by
+calling unlock_new_inode().
+
+The filesystem is responsible for setting (and possibly testing) i_ino
+when appropriate. There is also a simpler iget_locked function that
+just takes the superblock and inode number as arguments and does the
+test and set for you.
+
+e.g.::
+
+        inode = iget_locked(sb, ino);
+        if (inode->i_state & I_NEW) {
+                err = read_inode_from_disk(inode);
+                if (err < 0) {
+                        iget_failed(inode);
+                        return err;
+                }
+                unlock_new_inode(inode);
+        }
+
+Note that if the process of setting up a new inode fails, then iget_failed()
+should be called on the inode to render it dead, and an appropriate error
+should be passed back to the caller.
+
+---
+
+**recommended**
+
+->getattr() finally getting used.  See instances in nfs, minix, etc.
+
+---
+
+**mandatory**
+
+->revalidate() is gone.  If your filesystem had it - provide ->getattr()
+and let it call whatever you had as ->revlidate() + (for symlinks that
+had ->revalidate()) add calls in ->follow_link()/->readlink().
+
+---
+
+**mandatory**
+
+->d_parent changes are not protected by BKL anymore.  Read access is safe
+if at least one of the following is true:
+
+        * filesystem has no cross-directory rename()
+        * we know that parent had been locked (e.g. we are looking at
+          ->d_parent of ->lookup() argument).
+        * we are called from ->rename().
+        * the child's ->d_lock is held
+
+Audit your code and add locking if needed.  Notice that any place that is
+not protected by the conditions above is risky even in the old tree - you
+had been relying on BKL and that's prone to screwups.  Old tree had quite
+a few holes of that kind - unprotected access to ->d_parent leading to
+anything from oops to silent memory corruption.
+
+---
+
+**mandatory**
+
+FS_NOMOUNT is gone.  If you use it - just set SB_NOUSER in flags
+(see rootfs for one kind of solution and bdev/socket/pipe for another).
+
+---
+
+**recommended**
+
+Use bdev_read_only(bdev) instead of is_read_only(kdev).  The latter
+is still alive, but only because of the mess in drivers/s390/block/dasd.c.
+As soon as it gets fixed is_read_only() will die.
+
+---
+
+**mandatory**
+
+->permission() is called without BKL now. Grab it on entry, drop upon
+return - that will guarantee the same locking you used to have.  If
+your method or its parts do not need BKL - better yet, now you can
+shift lock_kernel() and unlock_kernel() so that they would protect
+exactly what needs to be protected.
+
+---
+
+**mandatory**
+
+->statfs() is now called without BKL held.  BKL should have been
+shifted into individual fs sb_op functions where it's not clear that
+it's safe to remove it.  If you don't need it, remove it.
+
+---
+
+**mandatory**
+
+is_read_only() is gone; use bdev_read_only() instead.
+
+---
+
+**mandatory**
+
+destroy_buffers() is gone; use invalidate_bdev().
+
+---
+
+**mandatory**
+
+fsync_dev() is gone; use fsync_bdev().  NOTE: lvm breakage is
+deliberate; as soon as struct block_device * is propagated in a reasonable
+way by that code fixing will become trivial; until then nothing can be
+done.
+
+**mandatory**
+
+block truncatation on error exit from ->write_begin, and ->direct_IO
+moved from generic methods (block_write_begin, cont_write_begin,
+nobh_write_begin, blockdev_direct_IO*) to callers.  Take a look at
+ext2_write_failed and callers for an example.
+
+**mandatory**
+
+->truncate is gone.  The whole truncate sequence needs to be
+implemented in ->setattr, which is now mandatory for filesystems
+implementing on-disk size changes.  Start with a copy of the old inode_setattr
+and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
+be in order of zeroing blocks using block_truncate_page or similar helpers,
+size update and on finally on-disk truncation which should not fail.
+setattr_prepare (which used to be inode_change_ok) now includes the size checks
+for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
+
+**mandatory**
+
+->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
+be used instead.  It gets called whenever the inode is evicted, whether it has
+remaining links or not.  Caller does *not* evict the pagecache or inode-associated
+metadata buffers; the method has to use truncate_inode_pages_final() to get rid
+of those. Caller makes sure async writeback cannot be running for the inode while
+(or after) ->evict_inode() is called.
+
+->drop_inode() returns int now; it's called on final iput() with
+inode->i_lock held and it returns true if filesystems wants the inode to be
+dropped.  As before, generic_drop_inode() is still the default and it's been
+updated appropriately.  generic_delete_inode() is also alive and it consists
+simply of return 1.  Note that all actual eviction work is done by caller after
+->drop_inode() returns.
+
+As before, clear_inode() must be called exactly once on each call of
+->evict_inode() (as it used to be for each call of ->delete_inode()).  Unlike
+before, if you are using inode-associated metadata buffers (i.e.
+mark_buffer_dirty_inode()), it's your responsibility to call
+invalidate_inode_buffers() before clear_inode().
+
+NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
+if it's zero is not *and* *never* *had* *been* enough.  Final unlink() and iput()
+may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
+free the on-disk inode, you may end up doing that while ->write_inode() is writing
+to it.
+
+---
+
+**mandatory**
+
+.d_delete() now only advises the dcache as to whether or not to cache
+unreferenced dentries, and is now only called when the dentry refcount goes to
+0. Even on 0 refcount transition, it must be able to tolerate being called 0,
+1, or more times (eg. constant, idempotent).
+
+---
+
+**mandatory**
+
+.d_compare() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+.d_hash() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
+for details of what locks to replace dcache_lock with in order to protect
+particular things. Most of the time, a filesystem only needs ->d_lock, which
+protects *all* the dcache state of a given dentry.
+
+---
+
+**mandatory**
+
+Filesystems must RCU-free their inodes, if they can have been accessed
+via rcu-walk path walk (basically, if the file can have had a path name in the
+vfs namespace).
+
+Even though i_dentry and i_rcu share storage in a union, we will
+initialize the former in inode_init_always(), so just leave it alone in
+the callback.  It used to be necessary to clean it there, but not anymore
+(starting at 3.2).
+
+---
+
+**recommended**
+
+vfs now tries to do path walking in "rcu-walk mode", which avoids
+atomic operations and scalability hazards on dentries and inodes (see
+Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
+(above) are examples of the changes required to support this. For more complex
+filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
+no changes are required to the filesystem. However, this is costly and loses
+the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
+are rcu-walk aware, shown below. Filesystems should take advantage of this
+where possible.
+
+---
+
+**mandatory**
+
+d_revalidate is a callback that is made on every path element (if
+the filesystem provides it), which requires dropping out of rcu-walk mode. This
+may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
+returned if the filesystem cannot handle rcu-walk. See
+Documentation/filesystems/vfs.rst for more details.
+
+permission is an inode permission check that is called on many or all
+directory inodes on the way down a path walk (to check for exec permission). It
+must now be rcu-walk aware (mask & MAY_NOT_BLOCK).  See
+Documentation/filesystems/vfs.rst for more details.
+
+---
+
+**mandatory**
+
+In ->fallocate() you must check the mode option passed in.  If your
+filesystem does not support hole punching (deallocating space in the middle of a
+file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
+Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
+so the i_size should not change when hole punching, even when puching the end of
+a file off.
+
+---
+
+**mandatory**
+
+->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
+a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
+the function type.  If you were doing it manually, just switch from setting
+->mnt_root to some pointer to returning that pointer.  On errors return
+ERR_PTR(...).
+
+---
+
+**mandatory**
+
+->permission() and generic_permission()have lost flags
+argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
+
+generic_permission() has also lost the check_acl argument; ACL checking
+has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
+to read an ACL from disk.
+
+---
+
+**mandatory**
+
+If you implement your own ->llseek() you must handle SEEK_HOLE and
+SEEK_DATA.  You can hanle this by returning -EINVAL, but it would be nicer to
+support it in some way.  The generic handler assumes that the entire file is
+data and there is a virtual hole at the end of the file.  So if the provided
+offset is less than i_size and SEEK_DATA is specified, return the same offset.
+If the above is true for the offset and you are given SEEK_HOLE, return the end
+of the file.  If the offset is i_size or greater return -ENXIO in either case.
+
+**mandatory**
+
+If you have your own ->fsync() you must make sure to call
+filemap_write_and_wait_range() so that all dirty pages are synced out properly.
+You must also keep in mind that ->fsync() is not called with i_mutex held
+anymore, so if you require i_mutex locking you must make sure to take it and
+release it yourself.
+
+---
+
+**mandatory**
+
+d_alloc_root() is gone, along with a lot of bugs caused by code
+misusing it.  Replacement: d_make_root(inode).  On success d_make_root(inode)
+allocates and returns a new dentry instantiated with the passed in inode.
+On failure NULL is returned and the passed in inode is dropped so the reference
+to inode is consumed in all cases and failure handling need not do any cleanup
+for the inode.  If d_make_root(inode) is passed a NULL inode it returns NULL
+and also requires no further error handling. Typical usage is::
+
+        inode = foofs_new_inode(....);
+        s->s_root = d_make_root(inode);
+        if (!s->s_root)
+                /* Nothing needed for the inode cleanup */
+                return -ENOMEM;
+        ...
+
+---
+
+**mandatory**
+
+The witch is dead!  Well, 2/3 of it, anyway.  ->d_revalidate() and
+->lookup() do *not* take struct nameidata anymore; just the flags.
+
+---
+
+**mandatory**
+
+->create() doesn't take ``struct nameidata *``; unlike the previous
+two, it gets "is it an O_EXCL or equivalent?" boolean argument.  Note that
+local filesystems can ignore tha argument - they are guaranteed that the
+object doesn't exist.  It's remote/distributed ones that might care...
+
+---
+
+**mandatory**
+
+FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
+in your dentry operations instead.
+
+---
+
+**mandatory**
+
+vfs_readdir() is gone; switch to iterate_dir() instead
+
+---
+
+**mandatory**
+
+->readdir() is gone now; switch to ->iterate()
+
+**mandatory**
+
+vfs_follow_link has been removed.  Filesystems must use nd_set_link
+from ->follow_link for normal symlinks, or nd_jump_link for magic
+/proc/<pid> style links.
+
+---
+
+**mandatory**
+
+iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
+called with both ->i_lock and inode_hash_lock held; the former is *not*
+taken anymore, so verify that your callbacks do not rely on it (none
+of the in-tree instances did).  inode_hash_lock is still held,
+of course, so they are still serialized wrt removal from inode hash,
+as well as wrt set() callback of iget5_locked().
+
+---
+
+**mandatory**
+
+d_materialise_unique() is gone; d_splice_alias() does everything you
+need now.  Remember that they have opposite orders of arguments ;-/
+
+---
+
+**mandatory**
+
+f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
+it entirely.
+
+---
+
+**mandatory**
+
+never call ->read() and ->write() directly; use __vfs_{read,write} or
+wrappers; instead of checking for ->write or ->read being NULL, look for
+FMODE_CAN_{WRITE,READ} in file->f_mode.
+
+---
+
+**mandatory**
+
+do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
+instead.
+
+---
+
+**mandatory**
+        ->aio_read/->aio_write are gone.  Use ->read_iter/->write_iter.
+
+---
+
+**recommended**
+
+for embedded ("fast") symlinks just set inode->i_link to wherever the
+symlink body is and use simple_follow_link() as ->follow_link().
+
+---
+
+**mandatory**
+
+calling conventions for ->follow_link() have changed.  Instead of returning
+cookie and using nd_set_link() to store the body to traverse, we return
+the body to traverse and store the cookie using explicit void ** argument.
+nameidata isn't passed at all - nd_jump_link() doesn't need it and
+nd_[gs]et_link() is gone.
+
+---
+
+**mandatory**
+
+calling conventions for ->put_link() have changed.  It gets inode instead of
+dentry,  it does not get nameidata at all and it gets called only when cookie
+is non-NULL.  Note that link body isn't available anymore, so if you need it,
+store it as cookie.
+
+---
+
+**mandatory**
+
+any symlink that might use page_follow_link_light/page_put_link() must
+have inode_nohighmem(inode) called before anything might start playing with
+its pagecache.  No highmem pages should end up in the pagecache of such
+symlinks.  That includes any preseeding that might be done during symlink
+creation.  __page_symlink() will honour the mapping gfp flags, so once
+you've done inode_nohighmem() it's safe to use, but if you allocate and
+insert the page manually, make sure to use the right gfp flags.
+
+---
+
+**mandatory**
+
+->follow_link() is replaced with ->get_link(); same API, except that
+
+        * ->get_link() gets inode as a separate argument
+        * ->get_link() may be called in RCU mode - in that case NULL
+          dentry is passed
+
+---
+
+**mandatory**
+
+->get_link() gets struct delayed_call ``*done`` now, and should do
+set_delayed_call() where it used to set ``*cookie``.
+
+->put_link() is gone - just give the destructor to set_delayed_call()
+in ->get_link().
+
+---
+
+**mandatory**
+
+->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode.
+
+---
+
+**mandatory**
+
+symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+i_pipe/i_link union zeroed out at inode eviction.  As the result, you can't
+assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
+to fix shmem_destroy_callback() that used to take that kind of shortcut;
+watch out, since that shortcut is no longer valid.
+
+---
+
+**mandatory**
+
+->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
+they used to - they just take it exclusive.  However, ->lookup() may be
+called with parent locked shared.  Its instances must not
+
+        * use d_instantiate) and d_rehash() separately - use d_add() or
+          d_splice_alias() instead.
+        * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+        * in the unlikely case when (read-only) access to filesystem
+          data structures needs exclusion for some reason, arrange it
+          yourself.  None of the in-tree filesystems needed that.
+        * rely on ->d_parent and ->d_name not changing after dentry has
+          been fed to d_add() or d_splice_alias().  Again, none of the
+          in-tree instances relied upon that.
+
+We are guaranteed that lookups of the same name in the same directory
+will not happen in parallel ("same" in the sense of your ->d_compare()).
+Lookups on different names in the same directory can and do happen in
+parallel now.
+
+---
+
+**recommended**
+
+->iterate_shared() is added; it's a parallel variant of ->iterate().
+Exclusion on struct file level is still provided (as well as that
+between it and lseek on the same struct file), but if your directory
+has been opened several times, you can get these called in parallel.
+Exclusion between that method and all directory-modifying ones is
+still provided, of course.
+
+Often enough ->iterate() can serve as ->iterate_shared() without any
+changes - it is a read-only operation, after all.  If you have any
+per-inode or per-dentry in-core data structures modified by ->iterate(),
+you might need something to serialize the access to them.  If you
+do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+that; look for in-tree examples.
+
+Old method is only used if the new one is absent; eventually it will
+be removed.  Switch while you still can; the old one won't stay.
+
+---
+
+**mandatory**
+
+->atomic_open() calls without O_CREAT may happen in parallel.
+
+---
+
+**mandatory**
+
+->setxattr() and xattr_handler.set() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
+->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
+
+---
+
+**mandatory**
+
+->d_compare() doesn't get parent as a separate argument anymore.  If you
+used it for finding the struct super_block involved, dentry->d_sb will
+work just as well; if it's something more complicated, use dentry->d_parent.
+Just be careful not to assume that fetching it more than once will yield
+the same value - in RCU mode it could change under you.
+
+---
+
+**mandatory**
+
+->rename() has an added flags argument.  Any flags not handled by the
+filesystem should result in EINVAL being returned.
+
+---
+
+
+**recommended**
+
+->readlink is optional for symlinks.  Don't set, unless filesystem needs
+to fake something for readlink(2).
+
+---
+
+**mandatory**
+
+->getattr() is now passed a struct path rather than a vfsmount and
+dentry separately, and it now has request_mask and query_flags arguments
+to specify the fields and sync type requested by statx.  Filesystems not
+supporting any statx-specific features may ignore the new arguments.
+
+---
+
+**mandatory**
+
+->atomic_open() calling conventions have changed.  Gone is ``int *opened``,
+along with FILE_OPENED/FILE_CREATED.  In place of those we have
+FMODE_OPENED/FMODE_CREATED, set in file->f_mode.  Additionally, return
+value for 'called finish_no_open(), open it yourself' case has become
+0, not 1.  Since finish_no_open() itself is returning 0 now, that part
+does not need any changes in ->atomic_open() instances.
+
+---
+
+**mandatory**
+
+alloc_file() has become static now; two wrappers are to be used instead.
+alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
+when dentry needs to be created; that's the majority of old alloc_file()
+users.  Calling conventions: on success a reference to new struct file
+is returned and callers reference to inode is subsumed by that.  On
+failure, ERR_PTR() is returned and no caller's references are affected,
+so the caller needs to drop the inode reference it held.
+alloc_file_clone(file, flags, ops) does not affect any caller's references.
+On success you get a new struct file sharing the mount/dentry with the
+original, on failure - ERR_PTR().
+
+---
+
+**mandatory**
+
+->clone_file_range() and ->dedupe_file_range have been replaced with
+->remap_file_range().  See Documentation/filesystems/vfs.rst for more
+information.
+
+---
+
+**recommended**
+
+->lookup() instances doing an equivalent of::
+
+        if (IS_ERR(inode))
+                return ERR_CAST(inode);
+        return d_splice_alias(inode, dentry);
+
+don't need to bother with the check - d_splice_alias() will do the
+right thing when given ERR_PTR(...) as inode.  Moreover, passing NULL
+inode to d_splice_alias() will also do the right thing (equivalent of
+d_add(dentry, NULL); return NULL;), so that kind of special cases
+also doesn't need a separate treatment.
+
+---
+
+**strongly recommended**
+
+take the RCU-delayed parts of ->destroy_inode() into a new method -
+->free_inode().  If ->destroy_inode() becomes empty - all the better,
+just get rid of it.  Synchronous work (e.g. the stuff that can't
+be done from an RCU callback, or any WARN_ON() where we want the
+stack trace) *might* be movable to ->evict_inode(); however,
+that goes only for the things that are not needed to balance something
+done by ->alloc_inode().  IOW, if it's cleaning up the stuff that
+might have accumulated over the life of in-core inode, ->evict_inode()
+might be a fit.
+
+Rules for inode destruction:
+
+        * if ->destroy_inode() is non-NULL, it gets called
+        * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
+        * combination of NULL ->destroy_inode and NULL ->free_inode is
+          treated as NULL/free_inode_nonrcu, to preserve the compatibility.
+
+Note that the callback (be it via ->free_inode() or explicit call_rcu()
+in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
+as the matter of fact, the superblock and all associated structures
+might be already gone.  The filesystem driver is guaranteed to be still
+there, but that's it.  Freeing memory in the callback is fine; doing
+more than that is possible, but requires a lot of care and is best
+avoided.
+
+---
+
+**mandatory**
+
+DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
+default.  DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
+business doing so.
+
+---
+
+**mandatory**
+
+d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
+very suspect (and won't work in modules).  Such uses are very likely to
+be misspelled d_alloc_anon().
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst
index 23e698167141..6a9584f6ff46 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -1,8 +1,11 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
+:orphan:
 
-# Introduction
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
 
 UBIFS utilizes the fscrypt framework to provide confidentiality for file
 contents and file names. This prevents attacks where an attacker is able to
@@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
 be possible to use UBIFS authentication without using encryption.
 
 
-## MTD, UBI & UBIFS
+MTD, UBI & UBIFS
+----------------
 
 On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
 interface to access raw flash devices. One of the more prominent subsystems that
@@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
 leveling and some flash specifics are left to UBI, while UBIFS focuses on
 scalability, performance and recoverability.
 
-
+::
 
         +------------+ +*******+ +-----------+ +-----+
         |            | * UBIFS * | UBI-BLOCK | | ... |
@@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
 [UBIFS-WP].
 
 
-### UBIFS Index & Tree Node Cache
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
 of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
 marked as dirty are written to the flash to update the persisted index.
 
 
-### Journal
+Journal
+~~~~~~~
 
 To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
 any changes (in form of inode nodes, data nodes etc.) between commits
 of the index. During mount, the journal is read from the flash and replayed
 onto the TNC (which will be created on-demand from the on-flash index).
 
 UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
 amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
 two types of nodes: *reference nodes* and *commit start nodes*. A commit start
 node is written whenever an index commit is performed. Reference nodes are
 written on every journal update. Each reference node points to the position of
@@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
 because of a power cut. If the recovery fails, UBIFS will not mount. An error
 for every other LEB will directly cause UBIFS to fail the mount operation.
 
+::
 
        | ----    LOG AREA     ---- | ----------    MAIN AREA    ------------ |
 
@@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
                           containing their buds
 
 
-### LEB Property Tree/Table
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
 the LEB. The type is important, because UBIFS never mixes index nodes with data
 nodes on a single LEB and thus each LEB has a specific purpose. This again is
 useful for free space calculations. See [UBIFS-WP] for more details.
@@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
 commit. Thus, saving the LPT is an atomic operation.
 
 
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+   difference between free space ie. the remaining space left on the LEB to be
+   written to without erasing it and previously written content that is obsolete
+   but can't be overwritten without erasing the full LEB.
 
 
-# UBIFS Authentication
+UBIFS Authentication
+====================
 
 This chapter introduces UBIFS authentication which enables UBIFS to verify
 the authenticity and integrity of metadata and file contents stored on flash.
 
 
-## Threat Model
+Threat Model
+------------
 
 UBIFS authentication enables detection of offline data modification. While it
 does not prevent it, it enables (trusted) code to check the integrity and
@@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
 ensure that only trusted code is executed on a device.
 
 
-## Authentication
+Authentication
+--------------
 
 To be able to fully trust data read from flash, all UBIFS data structures
 stored on flash are authenticated. That is:
@@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
 - The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
 
 
-### Index Authentication
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
 
 Through UBIFS' concept of a wandering tree, it already takes care of only
 updating and persisting changed parts from leaf node up to the root node
@@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
 the storage overhead which is precious for users of UBIFS (ie. embedded
 devices).
 
+::
 
                              +---------------+
                              |  Master Node  |
@@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
 atomically together with its respective node.
 
 
-### Journal Authentication
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
 
 The journal is authenticated too. Since the journal is continuously written
 it is necessary to also add authentication information frequently to the
@@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
 authentication node. The tail of the journal which may not have a authentication
 node cannot be authenticated and is skipped during journal replay.
 
-We get this picture for journal authentication:
+We get this picture for journal authentication::
 
     ,,,,,,,,
     ,......,...........................................
@@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
 modified on feature flag or similar changes, but never on file changes.
 
 
-### LPT Authentication
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
 
 The location of the LPT root node on the flash is stored in the UBIFS master
 node. Since the LPT is written and read atomically on every commit, there is
@@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
 LTP hash stored there with the hash computed from the read on-flash LPT.
 
 
-## Key Management
+Key Management
+--------------
 
 For simplicity, UBIFS authentication uses a single key to compute the HMACs
 of superblock, master, commit start and reference nodes. This key has to be
@@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
 [FSCRYPT-POLICY2].
 
 
-# Future Extensions
+Future Extensions
+=================
 
 In certain cases where a vendor wants to provide an authenticated filesystem
 image to customers, it should be possible to do so without sharing the secret
@@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
 will then have to be provided beforehand in the normal way.
 
 
-# References
+References
+==========
 
 [CRYPTSETUP2]        http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
 
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 0f85ab21c2ca..7d4d09dd5e6d 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist.
 
 VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
 are called from a process context.  Filesystem locking is described in
-the document Documentation/filesystems/Locking.
+the document Documentation/filesystems/locking.rst.
 
 
 Directory Entry Cache (dcache)
diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
index 6cbb0f75fe00..116fb2019956 100644
--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
 If nothing happens when loading the adm1021 module, and you are certain
 that your specific Xeon processor model includes compatible sensors, you
 will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
 addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
 only temp2 will be correct and temp1 will have to be ignored.
 
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 9a1913e5b4d9..49966ed70ec6 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 The ADM1075, unlike many other PMBus devices, does not support internal voltage
diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
index 649bd4be4fc2..e95d373eb693 100644
--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
 I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
 can be used in the board setup code.
 
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
 instantiate I2C devices.
 
 sysfs-Interface
diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
index 52e74e39463a..ef8f3f806968 100644
--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Sysfs entries
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index da15e3094c8c..30e6e77fb3c8 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
index 6d5e9538991f..c06249292557 100644
--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
index fa5c852a178c..45f69f334f25 100644
--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@ Usage Notes
 
 This driver does not probe for devices, since there is no register which
 can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 WARNING: Do not access chip registers using the i2cdump command, and do not use
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index aa4469be6674..fe701e07eaf5 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 939138e12b02..5744df100a5d 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 For MAX34446, the value of the currX_crit attribute determines if current or
diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
index 253482add082..7952b6ecaa2d 100644
--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@ Usage notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Module parameters
diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
index 009487759c61..71e7f2cbe2e2 100644
--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
index 1f0c6b2235ab..978691d5956d 100644
--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@ Usage Notes
 This driver is part of the MFD driver named "menf21bmc" and does
 not auto-detect devices.
 You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Sysfs entries
diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
index e98bd542a441..5c4e85f53177 100644
--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
 The PCF8591 is plainly impossible to detect! Thus the driver won't even
 try. You have to explicitly instantiate the device at the relevant
 address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
 for details.
 
 Directories are being created for each instantiated PCF8591:
diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
index 978a7117e4b2..95a850d5b2c1 100644
--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
 
 The device communicates with the I2C protocol. Sensors can have the I2C
 addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
 
 There are two options configurable by means of sht3x_platform_data:
 
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index 9b0f1eee5bf2..08380f21ab6a 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -45,7 +45,7 @@ chips, a humidity and temperature sensor. Temperature is measured in degrees
 celsius, relative humidity is expressed as a percentage.
 
 The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
 instantiate the device.
 
 There are two options configurable by means of shtc1_platform_data:
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 15d25806d585..205de6148fcb 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
 Documentation/hwmon/sysfs-interface.rst under Temperatures).
 
 Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index b691e30479dd..8fe3e1c3572e 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
index ebc4f2b3bfea..746f21fcb48c 100644
--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
index b819dfd75f71..4f0e7c3ca6f4 100644
--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
index a343c35df740..7ab9ddebcf79 100644
--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@ all as a 686A.
 
 The Via 686a southbridge has integrated hardware monitor functionality.
 It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
 
 The Via 686a implements three temperature sensors, two fan rotation speed
 sensors, five voltage sensors and alarms.
diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
index 41513bb7fe51..968aff10ce0a 100644
--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 .. warning::
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
index 5d46342e486a..6941064730dc 100644
--- a/Documentation/i2c/busses/i2c-ali1535
+++ b/Documentation/i2c/busses/i2c-ali1535.rst
@@ -1,16 +1,19 @@
+=========================
 Kernel driver i2c-ali1535
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1535 (south bridge)
+
     Datasheet: Now under NDA
         http://www.ali.com.tw/
 
 Authors:
-        Frodo Looijaard <frodol@dds.nl>,
-        Philip Edelbrock <phil@netroedge.com>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>,
-        Dan Eaton <dan.eaton@rocketlogix.com>,
-        Stephen Rousset<stephen.rousset@rocketlogix.com>
+        - Frodo Looijaard <frodol@dds.nl>,
+        - Philip Edelbrock <phil@netroedge.com>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+        - Dan Eaton <dan.eaton@rocketlogix.com>,
+        - Stephen Rousset<stephen.rousset@rocketlogix.com>
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
index 41b1a077e4c7..eec32c3ba92a 100644
--- a/Documentation/i2c/busses/i2c-ali1563
+++ b/Documentation/i2c/busses/i2c-ali1563.rst
@@ -1,7 +1,10 @@
+=========================
 Kernel driver i2c-ali1563
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1563 (south bridge)
+
     Datasheet: Now under NDA
         http://www.ali.com.tw/
 
diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
index 42888d8ac124..d4c1a2a419cb 100644
--- a/Documentation/i2c/busses/i2c-ali15x3
+++ b/Documentation/i2c/busses/i2c-ali15x3.rst
@@ -1,20 +1,23 @@
+=========================
 Kernel driver i2c-ali15x3
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+
     Datasheet: Now under NDA
         http://www.ali.com.tw/
 
 Authors:
-        Frodo Looijaard <frodol@dds.nl>,
-        Philip Edelbrock <phil@netroedge.com>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>
+        - Frodo Looijaard <frodol@dds.nl>,
+        - Philip Edelbrock <phil@netroedge.com>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>
 
 Module Parameters
 -----------------
 
 * force_addr: int
-  Initialize the base address of the i2c controller
+    Initialize the base address of the i2c controller
 
 
 Notes
@@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
 lspci. Don't use this unless the driver complains that the base address is
 not set.
 
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
+Example::
+
+    modprobe i2c-ali15x3 force_addr=0xe800
 
 SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
 by a power cycle. Cause unknown (see Issues below).
@@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
 M1541 and M1543C South Bridges.
 
 The M1543C is a South bridge for desktop systems.
+
 The M1541 is a South bridge for portable systems.
+
 They are part of the following ALI chipsets:
 
  * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
-                100MHz CPU Front Side bus
+   100MHz CPU Front Side bus
  * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
-                CPU Front Side bus
+   CPU Front Side bus
+
    Some Aladdin V motherboards:
-        Asus P5A
-        Atrend ATC-5220
-        BCM/GVC VP1541
-        Biostar M5ALA
-        Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
-                            enable the 7101 device! **)
-        Iwill XA100 Plus
-        Micronics C200
-        Microstar (MSI) MS-5169
+        - Asus P5A
+        - Atrend ATC-5220
+        - BCM/GVC VP1541
+        - Biostar M5ALA
+        - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
+          enable the 7101 device!)
+        - Iwill XA100 Plus
+        - Micronics C200
+        - Microstar (MSI) MS-5169
 
   * "Aladdin IV" includes the M1541 Socket 7 North bridge
-                with host bus up to 83.3 MHz.
+    with host bus up to 83.3 MHz.
 
 For an overview of these chips see http://www.acerlabs.com. At this time the
 full data sheets on the web site are password protected, however if you
 contact the ALI office in San Jose they may give you the password.
 
 The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
+output of lspci will show something similar to the following::
 
   00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
   00:03.0 Bridge: Acer Laboratories Inc. M7101      <= THIS IS THE ONE WE NEED
   00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
   00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
 
-** IMPORTANT **
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
-** then run lspci.
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
-** The driver won't work if it can't find the M7101 device.
+.. important::
+
+   If you have a M1533 or M1543C on the board and you get
+   "ali15x3: Error: Can't detect ali15x3!"
+   then run lspci.
+
+   If you see the 1533 and 5229 devices but NOT the 7101 device,
+   then you must enable ACPI, the PMU, SMB, or something similar
+   in the BIOS.
+
+   The driver won't work if it can't find the M7101 device.
 
 The SMB controller is part of the M7101 device, which is an ACPI-compliant
 Power Management Unit (PMU).
@@ -109,4 +120,3 @@ There may be electrical problems on this board.
 On the P5A, the W83781D sensor chip is on both the ISA and
 SMBus. Therefore the SMBus hangs can generally be avoided
 by accessing the W83781D on the ISA bus only.
-
diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2
deleted file mode 100644
index 6571487171f4..000000000000
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ /dev/null
@@ -1,23 +0,0 @@
-Kernel driver i2c-amd-mp2
-
-Supported adapters:
-  * AMD MP2 PCIe interface
-
-Datasheet: not publicly available.
-
-Authors:
-        Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
-        Nehal Shah <nehal-bakulchandra.shah@amd.com>
-        Elie Morisse <syniurge@gmail.com>
-
-Description
------------
-
-The MP2 is an ARM processor programmed as an I2C controller and communicating
-with the x86 host through PCI.
-
-If you see something like this:
-
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
-
-in your 'lspci -v', then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst
new file mode 100644
index 000000000000..ebc2fa899325
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
@@ -0,0 +1,25 @@
+=========================
+Kernel driver i2c-amd-mp2
+=========================
+
+Supported adapters:
+  * AMD MP2 PCIe interface
+
+Datasheet: not publicly available.
+
+Authors:
+        - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+        - Nehal Shah <nehal-bakulchandra.shah@amd.com>
+        - Elie Morisse <syniurge@gmail.com>
+
+Description
+-----------
+
+The MP2 is an ARM processor programmed as an I2C controller and communicating
+with the x86 host through PCI.
+
+If you see something like this::
+
+  03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+
+in your ``lspci -v``, then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
index 67f30874d0bf..bc93f392a4fc 100644
--- a/Documentation/i2c/busses/i2c-amd756
+++ b/Documentation/i2c/busses/i2c-amd756.rst
@@ -1,18 +1,22 @@
+========================
 Kernel driver i2c-amd756
+========================
 
 Supported adapters:
   * AMD 756
   * AMD 766
   * AMD 768
   * AMD 8111
+
     Datasheets: Publicly available on AMD website
 
   * nVidia nForce
+
     Datasheet: Unavailable
 
 Authors:
-        Frodo Looijaard <frodol@dds.nl>,
-        Philip Edelbrock <phil@netroedge.com> 
+        - Frodo Looijaard <frodol@dds.nl>,
+        - Philip Edelbrock <phil@netroedge.com>
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
index 460dd6635fd2..d08bf0a7f0ac 100644
--- a/Documentation/i2c/busses/i2c-amd8111
+++ b/Documentation/i2c/busses/i2c-amd8111.rst
@@ -1,4 +1,6 @@
+=========================
 Kernel driver i2c-adm8111
+=========================
 
 Supported adapters:
     * AMD-8111 SMBus 2.0 PCI interface
@@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
 Description
 -----------
 
-If you see something like this:
+If you see something like this::
 
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
-        Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
-        Flags: medium devsel, IRQ 19
-        I/O ports at d400 [size=32]
+  00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+          Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
+          Flags: medium devsel, IRQ 19
+          I/O ports at d400 [size=32]
 
-in your 'lspci -v', then this driver is for your chipset.
+in your ``lspci -v``, then this driver is for your chipset.
 
 Process Call Support
 --------------------
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
index 0d6018c316c7..c18cbdcdf73c 100644
--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
@@ -1,7 +1,10 @@
+============================
 Kernel driver i2c-diolan-u2c
+============================
 
 Supported adapters:
   * Diolan U2C-12 I2C-USB adapter
+
     Documentation:
         http://www.diolan.com/i2c/u2c12.html
 
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
index f426c13c63a9..2a570c214880 100644
--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -1,4 +1,7 @@
+======================
 Kernel driver i2c-i801
+======================
+
 
 Supported adapters:
   * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
@@ -39,28 +42,33 @@ Supported adapters:
   * Intel Comet Lake (PCH)
   * Intel Elkhart Lake (PCH)
   * Intel Tiger Lake (PCH)
+
    Datasheets: Publicly available at the Intel website
 
 On Intel Patsburg and later chipsets, both the normal host SMBus controller
 and the additional 'Integrated Device Function' controllers are supported.
 
-Authors: 
-        Mark Studebaker <mdsxyz123@yahoo.com>
-        Jean Delvare <jdelvare@suse.de>
+Authors:
+        - Mark Studebaker <mdsxyz123@yahoo.com>
+        - Jean Delvare <jdelvare@suse.de>
 
 
 Module Parameters
 -----------------
 
 * disable_features (bit vector)
+
 Disable selected features normally supported by the device. This makes it
 possible to work around possible driver or hardware bugs if the feature in
 question doesn't work as intended for whatever reason. Bit values:
+
+ ====  =========================================
  0x01  disable SMBus PEC
  0x02  disable the block buffer
  0x08  disable the I2C block read functionality
  0x10  don't use interrupts
  0x20  disable SMBus Host Notify
+ ====  =========================================
 
 
 Description
@@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others.
 
 The ICH chips contain at least SEVEN separate PCI functions in TWO logical
 PCI devices. An output of lspci will show something similar to the
-following:
+following::
 
   00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
   00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
@@ -139,14 +147,14 @@ and you think there's something interesting on the SMBus (e.g. a
 hardware monitoring chip), you need to add your board to the list.
 
 The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
 
-00:00.0 Class 0600: 8086:2570 (rev 02)
-        Subsystem: 1043:80f2
-        Flags: bus master, fast devsel, latency 0
-        Memory at fc000000 (32-bit, prefetchable) [size=32M]
-        Capabilities: [e4] #09 [2106]
-        Capabilities: [a0] AGP version 3.0
+  00:00.0 Class 0600: 8086:2570 (rev 02)
+          Subsystem: 1043:80f2
+          Flags: bus master, fast devsel, latency 0
+          Memory at fc000000 (32-bit, prefetchable) [size=32M]
+          Capabilities: [e4] #09 [2106]
+          Capabilities: [a0] AGP version 3.0
 
 Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
 (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
@@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's
 anything interesting on your hidden ICH SMBus.
 
 
-**********************
+----------------------------------------------------------------------------
+
 The lm_sensors project gratefully acknowledges the support of Texas
 Instruments in the initial development of this driver.
 
diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
index 737355822c0b..8e74919a3fdf 100644
--- a/Documentation/i2c/busses/i2c-ismt
+++ b/Documentation/i2c/busses/i2c-ismt.rst
@@ -1,4 +1,7 @@
+======================
 Kernel driver i2c-ismt
+======================
+
 
 Supported adapters:
   * Intel S12xx series SOCs
@@ -11,16 +14,21 @@ Module Parameters
 -----------------
 
 * bus_speed (unsigned int)
+
 Allows changing of the bus speed.  Normally, the bus speed is set by the BIOS
 and never needs to be changed.  However, some SMBus analyzers are too slow for
 monitoring the bus during debug, thus the need for this module parameter.
 Specify the bus speed in kHz.
+
 Available bus frequency settings:
-  0  no change
-  80 kHz
-  100 kHz
-  400 kHz
-  1000 kHz
+
+  ====   =========
+  0      no change
+  80     kHz
+  100    kHz
+  400    kHz
+  1000   kHz
+  ====   =========
 
 
 Description
@@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
 targeted primarily at the microserver and storage markets.
 
 The S12xx series contain a pair of PCI functions.  An output of lspci will show
-something similar to the following:
+something similar to the following::
 
   00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
   00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
index 925904aa9b57..9a0b2916aa71 100644
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
@@ -1,9 +1,12 @@
+==================
 Driver i2c-mlxcpld
+==================
 
 Author: Michael Shych <michaelsh@mellanox.com>
 
 This is the Mellanox I2C controller logic, implemented in Lattice CPLD
 device.
+
 Device supports:
  - Master mode.
  - One physical bus.
@@ -20,6 +23,8 @@ The next transaction types are supported:
  - Write Byte/Block.
 
 Registers:
+
+=============== === =======================================================================
 CPBLTY          0x0 - capability reg.
                         Bits [6:5] - transaction length. b01 - 72B is supported,
                         36B in other case.
@@ -49,3 +54,4 @@ DATAx		0xa - 0x54  - 68 bytes data buffer regs.
                         For read transactions address is sent in a separate transaction and
                         specified in the four first bytes (DATA0 - DATA3). Data is read
                         starting from DATA0.
+=============== === =======================================================================
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
index 9698c396b830..83181445268f 100644
--- a/Documentation/i2c/busses/i2c-nforce2
+++ b/Documentation/i2c/busses/i2c-nforce2.rst
@@ -1,10 +1,12 @@
+=========================
 Kernel driver i2c-nforce2
+=========================
 
 Supported adapters:
-  * nForce2 MCP                10de:0064 
-  * nForce2 Ultra 400 MCP      10de:0084 
-  * nForce3 Pro150 MCP         10de:00D4 
-  * nForce3 250Gb MCP          10de:00E4 
+  * nForce2 MCP                10de:0064
+  * nForce2 Ultra 400 MCP      10de:0084
+  * nForce3 Pro150 MCP         10de:00D4
+  * nForce3 250Gb MCP          10de:00E4
   * nForce4 MCP                10de:0052
   * nForce4 MCP-04             10de:0034
   * nForce MCP51               10de:0264
@@ -16,26 +18,27 @@ Supported adapters:
   * nForce MCP78S              10de:0752
   * nForce MCP79               10de:0AA2
 
-Datasheet: not publicly available, but seems to be similar to the
+Datasheet:
+           not publicly available, but seems to be similar to the
            AMD-8111 SMBus 2.0 adapter.
 
 Authors:
-        Hans-Frieder Vogt <hfvogt@gmx.net>,
-        Thomas Leibold <thomas@plx.com>, 
-        Patrick Dreker <patrick@dreker.de>
-        
+        - Hans-Frieder Vogt <hfvogt@gmx.net>,
+        - Thomas Leibold <thomas@plx.com>,
+        - Patrick Dreker <patrick@dreker.de>
+
 Description
 -----------
 
 i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
 
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
 
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
-        Subsystem: Asustek Computer, Inc.: Unknown device 0c11
-        Flags: 66Mhz, fast devsel, IRQ 5
-        I/O ports at c000 [size=32]
-        Capabilities: <available only to root>
+  00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+          Subsystem: Asustek Computer, Inc.: Unknown device 0c11
+          Flags: 66Mhz, fast devsel, IRQ 5
+          I/O ports at c000 [size=32]
+          Capabilities: <available only to root>
 
 then this driver should support the SMBuses of your motherboard.
 
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
index 31884d2b2eb5..38fb8a4c8756 100644
--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
@@ -1,4 +1,6 @@
+============================
 Kernel driver i2c-nvidia-gpu
+============================
 
 Datasheet: not publicly available.
 
@@ -11,8 +13,8 @@ Description
 i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
 and later GPUs and it is used to communicate with Type-C controller on GPUs.
 
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
 
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+  01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
 
 then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
index 9caaf7df1b2f..f5e175f2a2a6 100644
--- a/Documentation/i2c/busses/i2c-ocores
+++ b/Documentation/i2c/busses/i2c-ocores.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver i2c-ocores
+========================
 
 Supported adapters:
   * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
@@ -23,9 +25,9 @@ distance between registers and the input clock speed.
 There is also a possibility to attach a list of i2c_board_info which
 the i2c-ocores driver will add to the bus upon creation.
 
-E.G. something like:
+E.G. something like::
 
-static struct resource ocores_resources[] = {
+  static struct resource ocores_resources[] = {
         [0] = {
                 .start  = MYI2C_BASEADDR,
                 .end    = MYI2C_BASEADDR + 8,
@@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
                 .end    = MYI2C_IRQ,
                 .flags  = IORESOURCE_IRQ,
         },
-};
+  };
 
-/* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
+  /* optional board info */
+  struct i2c_board_info ocores_i2c_board_info[] = {
         {
                 I2C_BOARD_INFO("tsc2003", 0x48),
                 .platform_data = &tsc2003_platform_data,
@@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
                 I2C_BOARD_INFO("adv7180", 0x42 >> 1),
                 .irq = ADV_IRQ
         }
-};
+  };
 
-static struct ocores_i2c_platform_data myi2c_data = {
+  static struct ocores_i2c_platform_data myi2c_data = {
         .regstep        = 2,            /* two bytes between registers */
         .clock_khz      = 50000,        /* input clock of 50MHz */
         .devices        = ocores_i2c_board_info, /* optional table of devices */
         .num_devices    = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
+  };
 
-static struct platform_device myi2c = {
+  static struct platform_device myi2c = {
         .name                   = "ocores-i2c",
         .dev = {
                 .platform_data  = &myi2c_data,
         },
         .num_resources          = ARRAY_SIZE(ocores_resources),
         .resource               = ocores_resources,
-};
+  };
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
deleted file mode 100644
index c3dbb3bfd814..000000000000
--- a/Documentation/i2c/busses/i2c-parport
+++ /dev/null
@@ -1,178 +0,0 @@
-Kernel driver i2c-parport
-
-Author: Jean Delvare <jdelvare@suse.de>
-
-This is a unified driver for several i2c-over-parallel-port adapters,
-such as the ones made by Philips, Velleman or ELV. This driver is
-meant as a replacement for the older, individual drivers:
- * i2c-philips-par
- * i2c-elv
- * i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
-                      teletext adapters)
-
-It currently supports the following devices:
- * (type=0) Philips adapter
- * (type=1) home brew teletext adapter
- * (type=2) Velleman K8000 adapter
- * (type=3) ELV adapter
- * (type=4) Analog Devices ADM1032 evaluation board
- * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
- * (type=6) Barco LPT->DVI (K5800236) adapter
- * (type=7) One For All JP1 parallel port adapter
- * (type=8) VCT-jig
-
-These devices use different pinout configurations, so you have to tell
-the driver what you have, using the type module parameter. There is no
-way to autodetect the devices. Support for different pinout configurations
-can be easily added when needed.
-
-Earlier kernels defaulted to type=0 (Philips).  But now, if the type
-parameter is missing, the driver will simply fail to initialize.
-
-SMBus alert support is available on adapters which have this line properly
-connected to the parallel port's interrupt pin.
-
-
-Building your own adapter
--------------------------
-
-If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
-
-Device                                                      PC
-Side          ___________________Vdd (+)                    Side
-               |    |         |
-              ---  ---       ---
-              | |  | |       | |
-              |R|  |R|       |R|
-              | |  | |       | |
-              ---  ---       ---
-               |    |         |
-               |    |    /|   |
-SCL  ----------x--------o |-----------x-------------------  pin 2
-                    |    \|   |       |
-                    |         |       |
-                    |   |\    |       |
-SDA  ----------x----x---| o---x---------------------------  pin 13
-               |        |/            |
-               |                      |
-               |         /|           |
-               ---------o |----------------x--------------  pin 3
-                         \|           |    |
-                                      |    |
-                                     ---  ---
-                                     | |  | |
-                                     |R|  |R|
-                                     | |  | |
-                                     ---  ---
-                                      |    | 
-                                     ###  ###
-                                     GND  GND
-        
-Remarks:
- - This is the exact pinout and electronics used on the Analog Devices
-   evaluation boards.
-                   /|
- - All inverters -o |- must be 74HC05, they must be open collector output.
-                   \|
- - All resitors are 10k.
- - Pins 18-25 of the parallel port connected to GND.
- - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
-   The ADM1032 evaluation board uses D4-D7. Beware that the amount of
-   current you can draw from the parallel port is limited. Also note that
-   all connected lines MUST BE driven at the same state, else you'll short
-   circuit the output buffers! So plugging the I2C adapter after loading
-   the i2c-parport module might be a good safety since data line state
-   prior to init may be unknown. 
- - This is 5V!
- - Obviously you cannot read SCL (so it's not really standard-compliant).
-   Pretty easy to add, just copy the SDA part and use another input pin.
-   That would give (ELV compatible pinout):
-
-
-Device                                                      PC
-Side          ______________________________Vdd (+)         Side
-               |    |            |    |
-              ---  ---          ---  ---
-              | |  | |          | |  | |
-              |R|  |R|          |R|  |R|
-              | |  | |          | |  | |
-              ---  ---          ---  ---
-               |    |            |    |
-               |    |      |\    |    |
-SCL  ----------x--------x--| o---x------------------------  pin 15
-                    |   |  |/         | 
-                    |   |             |
-                    |   |   /|        |
-                    |   ---o |-------------x--------------  pin 2
-                    |       \|        |    |
-                    |                 |    |
-                    |                 |    |
-                    |      |\         |    |
-SDA  ---------------x---x--| o--------x-------------------  pin 10
-                        |  |/              |
-                        |                  |
-                        |   /|             |
-                        ---o |------------------x---------  pin 3
-                            \|             |    |
-                                           |    |
-                                          ---  ---
-                                          | |  | |
-                                          |R|  |R|
-                                          | |  | |
-                                          ---  ---
-                                           |    | 
-                                          ###  ###
-                                          GND  GND
-
-
-If possible, you should use the same pinout configuration as existing
-adapters do, so you won't even have to change the code.
-
-
-Similar (but different) drivers
--------------------------------
-
-This driver is NOT the same as the i2c-pport driver found in the i2c
-package. The i2c-pport driver makes use of modern parallel port features so
-that you don't need additional electronics. It has other restrictions
-however, and was not ported to Linux 2.6 (yet).
-
-This driver is also NOT the same as the i2c-pcf-epp driver found in the
-lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
-an I2C bus directly. Instead, it uses it to control an external I2C bus
-master. That driver was not ported to Linux 2.6 (yet) either.
-
-
-Legacy documentation for Velleman adapter
------------------------------------------
-
-Useful links:
-Velleman                http://www.velleman.be/
-Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
-
-The project has lead to new libs for the Velleman K8000 and K8005:
-  LIBK8000 v1.99.1 and LIBK8005 v0.21
-With these libs, you can control the K8000 interface card and the K8005
-stepper motor card with the simple commands which are in the original
-Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
-many more, using /dev/velleman.
-  http://home.wanadoo.nl/hihihi/libk8000.htm
-  http://home.wanadoo.nl/hihihi/libk8005.htm
-  http://struyve.mine.nu:8080/index.php?block=k8000
-  http://sourceforge.net/projects/libk8005/
-
-
-One For All JP1 parallel port adapter
--------------------------------------
-
-The JP1 project revolves around a set of remote controls which expose
-the I2C bus their internal configuration EEPROM lives on via a 6 pin
-jumper in the battery compartment. More details can be found at:
-
-http://www.hifi-remote.com/jp1/
-
-Details of the simple parallel port hardware can be found at:
-
-http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
index 7071b8ba0af4..e73af975d2c8 100644
--- a/Documentation/i2c/busses/i2c-parport-light
+++ b/Documentation/i2c/busses/i2c-parport-light.rst
@@ -1,13 +1,15 @@
+===============================
 Kernel driver i2c-parport-light
+===============================
 
 Author: Jean Delvare <jdelvare@suse.de>
 
-This driver is a light version of i2c-parport. It doesn't depend        
+This driver is a light version of i2c-parport. It doesn't depend
 on the parport driver, and uses direct I/O access instead. This might be
 preferred on embedded systems where wasting memory for the clean but heavy
 parport handling is not an option. The drawback is a reduced portability
-and the impossibility to daisy-chain other parallel port devices.                 
-  
+and the impossibility to daisy-chain other parallel port devices.
+
 Please see i2c-parport for documentation.
 
 Module parameters:
diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst
new file mode 100644
index 000000000000..a9b4e8133700
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport.rst
@@ -0,0 +1,190 @@
+=========================
+Kernel driver i2c-parport
+=========================
+
+Author: Jean Delvare <jdelvare@suse.de>
+
+This is a unified driver for several i2c-over-parallel-port adapters,
+such as the ones made by Philips, Velleman or ELV. This driver is
+meant as a replacement for the older, individual drivers:
+
+ * i2c-philips-par
+ * i2c-elv
+ * i2c-velleman
+ * video/i2c-parport
+   (NOT the same as this one, dedicated to home brew teletext adapters)
+
+It currently supports the following devices:
+
+ * (type=0) Philips adapter
+ * (type=1) home brew teletext adapter
+ * (type=2) Velleman K8000 adapter
+ * (type=3) ELV adapter
+ * (type=4) Analog Devices ADM1032 evaluation board
+ * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
+ * (type=6) Barco LPT->DVI (K5800236) adapter
+ * (type=7) One For All JP1 parallel port adapter
+ * (type=8) VCT-jig
+
+These devices use different pinout configurations, so you have to tell
+the driver what you have, using the type module parameter. There is no
+way to autodetect the devices. Support for different pinout configurations
+can be easily added when needed.
+
+Earlier kernels defaulted to type=0 (Philips).  But now, if the type
+parameter is missing, the driver will simply fail to initialize.
+
+SMBus alert support is available on adapters which have this line properly
+connected to the parallel port's interrupt pin.
+
+
+Building your own adapter
+-------------------------
+
+If you want to build you own i2c-over-parallel-port adapter, here is
+a sample electronics schema (credits go to Sylvain Munaut)::
+
+  Device                                                      PC
+  Side          ___________________Vdd (+)                    Side
+                 |    |         |
+                ---  ---       ---
+                | |  | |       | |
+                |R|  |R|       |R|
+                | |  | |       | |
+                ---  ---       ---
+                 |    |         |
+                 |    |    /|   |
+  SCL  ----------x--------o |-----------x-------------------  pin 2
+                      |    \|   |       |
+                      |         |       |
+                      |   |\    |       |
+  SDA  ----------x----x---| o---x---------------------------  pin 13
+                 |        |/            |
+                 |                      |
+                 |         /|           |
+                 ---------o |----------------x--------------  pin 3
+                           \|           |    |
+                                        |    |
+                                       ---  ---
+                                       | |  | |
+                                       |R|  |R|
+                                       | |  | |
+                                       ---  ---
+                                        |    |
+                                       ###  ###
+                                       GND  GND
+
+Remarks:
+ - This is the exact pinout and electronics used on the Analog Devices
+   evaluation boards.
+ - All inverters::
+
+                   /|
+                 -o |-
+                   \|
+
+   must be 74HC05, they must be open collector output.
+ - All resitors are 10k.
+ - Pins 18-25 of the parallel port connected to GND.
+ - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
+   The ADM1032 evaluation board uses D4-D7. Beware that the amount of
+   current you can draw from the parallel port is limited. Also note that
+   all connected lines MUST BE driven at the same state, else you'll short
+   circuit the output buffers! So plugging the I2C adapter after loading
+   the i2c-parport module might be a good safety since data line state
+   prior to init may be unknown.
+ - This is 5V!
+ - Obviously you cannot read SCL (so it's not really standard-compliant).
+   Pretty easy to add, just copy the SDA part and use another input pin.
+   That would give (ELV compatible pinout)::
+
+
+      Device                                                      PC
+      Side          ______________________________Vdd (+)         Side
+                     |    |            |    |
+                    ---  ---          ---  ---
+                    | |  | |          | |  | |
+                    |R|  |R|          |R|  |R|
+                    | |  | |          | |  | |
+                    ---  ---          ---  ---
+                     |    |            |    |
+                     |    |      |\    |    |
+      SCL  ----------x--------x--| o---x------------------------  pin 15
+                          |   |  |/         |
+                          |   |             |
+                          |   |   /|        |
+                          |   ---o |-------------x--------------  pin 2
+                          |       \|        |    |
+                          |                 |    |
+                          |                 |    |
+                          |      |\         |    |
+      SDA  ---------------x---x--| o--------x-------------------  pin 10
+                              |  |/              |
+                              |                  |
+                              |   /|             |
+                              ---o |------------------x---------  pin 3
+                                  \|             |    |
+                                                 |    |
+                                                ---  ---
+                                                | |  | |
+                                                |R|  |R|
+                                                | |  | |
+                                                ---  ---
+                                                 |    |
+                                                ###  ###
+                                                GND  GND
+
+
+If possible, you should use the same pinout configuration as existing
+adapters do, so you won't even have to change the code.
+
+
+Similar (but different) drivers
+-------------------------------
+
+This driver is NOT the same as the i2c-pport driver found in the i2c
+package. The i2c-pport driver makes use of modern parallel port features so
+that you don't need additional electronics. It has other restrictions
+however, and was not ported to Linux 2.6 (yet).
+
+This driver is also NOT the same as the i2c-pcf-epp driver found in the
+lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
+an I2C bus directly. Instead, it uses it to control an external I2C bus
+master. That driver was not ported to Linux 2.6 (yet) either.
+
+
+Legacy documentation for Velleman adapter
+-----------------------------------------
+
+Useful links:
+
+- Velleman                http://www.velleman.be/
+- Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
+
+The project has lead to new libs for the Velleman K8000 and K8005:
+
+  LIBK8000 v1.99.1 and LIBK8005 v0.21
+
+With these libs, you can control the K8000 interface card and the K8005
+stepper motor card with the simple commands which are in the original
+Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
+many more, using /dev/velleman.
+
+  - http://home.wanadoo.nl/hihihi/libk8000.htm
+  - http://home.wanadoo.nl/hihihi/libk8005.htm
+  - http://struyve.mine.nu:8080/index.php?block=k8000
+  - http://sourceforge.net/projects/libk8005/
+
+
+One For All JP1 parallel port adapter
+-------------------------------------
+
+The JP1 project revolves around a set of remote controls which expose
+the I2C bus their internal configuration EEPROM lives on via a 6 pin
+jumper in the battery compartment. More details can be found at:
+
+http://www.hifi-remote.com/jp1/
+
+Details of the simple parallel port hardware can be found at:
+
+http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
index b044e5265488..a254010c8055 100644
--- a/Documentation/i2c/busses/i2c-pca-isa
+++ b/Documentation/i2c/busses/i2c-pca-isa.rst
@@ -1,6 +1,9 @@
+=========================
 Kernel driver i2c-pca-isa
+=========================
 
 Supported adapters:
+
 This driver supports ISA boards using the Philips PCA 9564
 Parallel bus to I2C bus controller
 
@@ -10,11 +13,11 @@ Module Parameters
 -----------------
 
 * base int
- I/O base address
+    I/O base address
 * irq int
- IRQ interrupt
+    IRQ interrupt
 * clock int
- Clock rate as described in table 1 of PCA9564 datasheet
+    Clock rate as described in table 1 of PCA9564 datasheet
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
index 2703bc3acad0..cc9000259223 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4.rst
@@ -1,4 +1,6 @@
+=======================
 Kernel driver i2c-piix4
+=======================
 
 Supported adapters:
   * Intel 82371AB PIIX4 and PIIX4E
@@ -20,9 +22,9 @@ Supported adapters:
   * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
     Datasheet: Publicly available at the SMSC website http://www.smsc.com
 
-Authors: 
-        Frodo Looijaard <frodol@dds.nl>
-        Philip Edelbrock <phil@netroedge.com>
+Authors:
+        - Frodo Looijaard <frodol@dds.nl>
+        - Philip Edelbrock <phil@netroedge.com>
 
 
 Module Parameters
@@ -39,16 +41,16 @@ Description
 
 The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
 functionality. Among other things, it implements the PCI bus. One of its
-minor functions is implementing a System Management Bus. This is a true 
+minor functions is implementing a System Management Bus. This is a true
 SMBus - you can not access it on I2C levels. The good news is that it
 natively understands SMBus commands and you do not have to worry about
 timing problems. The bad news is that non-SMBus devices connected to it can
 confuse it mightily. Yes, this is known to happen...
 
-Do 'lspci -v' and see whether it contains an entry like this:
+Do ``lspci -v`` and see whether it contains an entry like this::
 
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
-             Flags: medium devsel, IRQ 9
+  0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+               Flags: medium devsel, IRQ 9
 
 Bus and device numbers may differ, but the function number must be
 identical (like many PCI devices, the PIIX4 incorporates a number of
@@ -91,7 +93,7 @@ the SMI mode.
    device is located at 00:0f.0.
 2) Now you just need to change the value in 0xD2 register. Get it first with
    command: lspci -xxx -s 00:0f.0
-   If the value is 0x3 then you need to change it to 0x1
+   If the value is 0x3 then you need to change it to 0x1:
    setpci  -s 00:0f.0 d2.b=1
 
 Please note that you don't need to do that in all cases, just when the SMBus is
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
index ecd21fb49a8f..b85630c84a96 100644
--- a/Documentation/i2c/busses/i2c-sis5595
+++ b/Documentation/i2c/busses/i2c-sis5595.rst
@@ -1,9 +1,11 @@
+=========================
 Kernel driver i2c-sis5595
+=========================
 
 Authors:
-        Frodo Looijaard <frodol@dds.nl>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>,
-        Philip Edelbrock <phil@netroedge.com>
+        - Frodo Looijaard <frodol@dds.nl>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+        - Philip Edelbrock <phil@netroedge.com>
 
 Supported adapters:
   * Silicon Integrated Systems Corp. SiS5595 Southbridge
@@ -11,14 +13,19 @@ Supported adapters:
 
 Note: all have mfr. ID 0x1039.
 
+   =========            ======
    SUPPORTED            PCI ID
+   =========            ======
         5595            0008
+   =========            ======
 
    Note: these chips contain a 0008 device which is incompatible with the
          5595. We recognize these by the presence of the listed
          "blacklist" PCI ID and refuse to load.
 
+   =============        ======          ================
    NOT SUPPORTED        PCI ID          BLACKLIST PCI ID
+   =============        ======          ================
          540            0008            0540
          550            0008            0550
         5513            0008            5511
@@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
          735            0008            0735
          745            0008            0745
          746            0008            0746
+   =============        ======          ================
 
 Module Parameters
 -----------------
 
-* force_addr=0xaddr     Set the I/O base address. Useful for boards
+==================      =====================================================
+force_addr=0xaddr       Set the I/O base address. Useful for boards
                         that don't set the address in the BIOS. Does not do a
                         PCI force; the device must still be present in lspci.
                         Don't use this unless the driver complains that the
                         base address is not set.
+==================      =====================================================
 
 Description
 -----------
@@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595
 chip, you want the sis5595 driver for those, not this driver. This driver
 is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
 drivers to access chips on the bus.
-
diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630
deleted file mode 100644
index ee7943631074..000000000000
--- a/Documentation/i2c/busses/i2c-sis630
+++ /dev/null
@@ -1,58 +0,0 @@
-Kernel driver i2c-sis630
-
-Supported adapters:
-  * Silicon Integrated Systems Corp (SiS)
-        630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
-        730 chipset
-        964 chipset
-  * Possible other SiS chipsets ?
-
-Author: Alexander Malysh <amalysh@web.de>
-        Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
-
-Module Parameters
------------------
-
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
-                This can be interesting for chipsets not named
-                above to check if it works for you chipset, but DANGEROUS!
-
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
-                        what your BIOS use). DANGEROUS! This should be a bit
-                        faster, but freeze some systems (i.e. my Laptop).
-                        SIS630/730 chip only.
-
-
-Description
------------
-
-This SMBus only driver is known to work on motherboards with the above
-named chipsets.
-
-If you see something like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-
-or like this:
-
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
-                                                        LPC Controller (rev 36)
-
-in your 'lspci' output , then this driver is for your chipset.
-
-Thank You
----------
-Philip Edelbrock <phil@netroedge.com>
-- testing SiS730 support
-Mark M. Hoffman <mhoffman@lightlink.com>
-- bug fixes
-
-To anyone else which I forgot here ;), thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst
new file mode 100644
index 000000000000..9fcd74b18781
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis630.rst
@@ -0,0 +1,63 @@
+========================
+Kernel driver i2c-sis630
+========================
+
+Supported adapters:
+  * Silicon Integrated Systems Corp (SiS)
+        630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux)
+        730 chipset
+        964 chipset
+  * Possible other SiS chipsets ?
+
+Author:
+        - Alexander Malysh <amalysh@web.de>
+        - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+
+Module Parameters
+-----------------
+
+==================      =====================================================
+force = [1|0]           Forcibly enable the SIS630. DANGEROUS!
+                        This can be interesting for chipsets not named
+                        above to check if it works for you chipset,
+                        but DANGEROUS!
+
+high_clock = [1|0]      Forcibly set Host Master Clock to 56KHz (default,
+                        what your BIOS use). DANGEROUS! This should be a bit
+                        faster, but freeze some systems (i.e. my Laptop).
+                        SIS630/730 chip only.
+==================      =====================================================
+
+
+Description
+-----------
+
+This SMBus only driver is known to work on motherboards with the above
+named chipsets.
+
+If you see something like this::
+
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+
+or like this::
+
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+                                                        LPC Controller (rev 36)
+
+in your ``lspci`` output , then this driver is for your chipset.
+
+Thank You
+---------
+Philip Edelbrock <phil@netroedge.com>
+- testing SiS730 support
+Mark M. Hoffman <mhoffman@lightlink.com>
+- bug fixes
+
+To anyone else which I forgot here ;), thanks!
diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
index 0b979f3252a4..437cc1d89588 100644
--- a/Documentation/i2c/busses/i2c-sis96x
+++ b/Documentation/i2c/busses/i2c-sis96x.rst
@@ -1,13 +1,18 @@
+========================
 Kernel driver i2c-sis96x
+========================
 
 Replaces 2.4.x i2c-sis645
 
 Supported adapters:
+
   * Silicon Integrated Systems Corp (SiS)
+
     Any combination of these host bridges:
         645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
+
     and these south bridges:
-        961, 962, 963(L)
+        961, 962, 963(L)
 
 Author: Mark M. Hoffman <mhoffman@lightlink.com>
 
@@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
 place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
 SiS630 datasheet (and  driver).
 
-The command "lspci" as root should produce something like these lines:
+The command ``lspci`` as root should produce something like these lines::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
 
-or perhaps this...
+or perhaps this::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
 
 (kernel versions later than 2.4.18 may fill in the "Unknown"s)
 
@@ -50,7 +55,7 @@ TO DOs
 ------
 
 * The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
+  scenario is found where they're needed.
 
 
 Thank You
@@ -58,16 +63,20 @@ Thank You
 
 Mark D. Studebaker <mdsxyz123@yahoo.com>
  - design hints and bug fixes
+
 Alexander Maylsh <amalysh@web.de>
  - ditto, plus an important datasheet... almost the one I really wanted
+
 Hans-Günter Lütke Uphues <hg_lu@t-online.de>
  - patch for SiS735
+
 Robert Zwerus <arzie@dds.nl>
  - testing for SiS645DX
+
 Kianusch Sayah Karadji <kianusch@sk-tech.net>
  - patch for SiS645DX/962
+
 Ken Healy
  - patch for SiS655
 
 To anyone else who has written w/ feedback, thanks!
-
diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
index 60299555dcf0..f342e313ee3d 100644
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ b/Documentation/i2c/busses/i2c-taos-evm.rst
@@ -1,4 +1,6 @@
+==========================
 Kernel driver i2c-taos-evm
+==========================
 
 Author: Jean Delvare <jdelvare@suse.de>
 
@@ -23,10 +25,10 @@ Using this driver
 In order to use this driver, you'll need the serport driver, and the
 inputattach tool, which is part of the input-utils package. The following
 commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
+serial port::
 
-# modprobe serport
-# inputattach --taos-evm /dev/ttyS0
+  # modprobe serport
+  # inputattach --taos-evm /dev/ttyS0
 
 
 Technical details
diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
index 343870661ac3..846aa17d80a2 100644
--- a/Documentation/i2c/busses/i2c-via
+++ b/Documentation/i2c/busses/i2c-via.rst
@@ -1,4 +1,6 @@
+=====================
 Kernel driver i2c-via
+=====================
 
 Supported adapters:
   * VIA Technologies, InC. VT82C586B
@@ -12,23 +14,27 @@ Description
 i2c-via is an i2c bus driver for motherboards with VIA chipset.
 
 The following VIA pci chipsets are supported:
- - MVP3, VP3, VP2/97, VPX/97 
+ - MVP3, VP3, VP2/97, VPX/97
  - others with South bridge VT82C586B
 
-Your lspci listing must show this :
+Your ``lspci`` listing must show this ::
 
  Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
 
-    Problems?
- 
- Q: You have VT82C586B on the motherboard, but not in the listing. 
- 
- A: Go to your BIOS setup, section PCI devices or similar.
-    Turn USB support on, and try again. 
+Problems?
+---------
 
- Q: No error messages, but still i2c doesn't seem to work.
+ Q:
+    You have VT82C586B on the motherboard, but not in the listing.
 
- A: This can happen. This driver uses the pins VIA recommends in their
+ A:
+    Go to your BIOS setup, section PCI devices or similar.
+    Turn USB support on, and try again.
+
+ Q:
+    No error messages, but still i2c doesn't seem to work.
+
+ A:
+    This can happen. This driver uses the pins VIA recommends in their
     datasheets, but there are several ways the motherboard manufacturer
     can actually wire the lines.
-
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
index ab64ce21c254..1762f0cf93d0 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver i2c-viapro
+========================
 
 Supported adapters:
   * VIA Technologies, Inc. VT82C596A/B
@@ -26,9 +28,9 @@ Supported adapters:
     Datasheet: available on http://linux.via.com.tw
 
 Authors:
-        Kyösti Mälkki <kmalkki@cc.hut.fi>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>,
-        Jean Delvare <jdelvare@suse.de>
+        - Kyösti Mälkki <kmalkki@cc.hut.fi>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+        - Jean Delvare <jdelvare@suse.de>
 
 Module Parameters
 -----------------
@@ -44,8 +46,9 @@ Description
 i2c-viapro is a true SMBus host driver for motherboards with one of the
 supported VIA south bridges.
 
-Your lspci -n listing must show one of these :
+Your ``lspci -n`` listing must show one of these :
 
+ ================   ======================
  device 1106:3050   (VT82C596A function 3)
  device 1106:3051   (VT82C596B function 3)
  device 1106:3057   (VT82C686 function 4)
@@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
  device 1106:8353   (VX800/VX820)
  device 1106:8409   (VX855/VX875)
  device 1106:8410   (VX900)
+ ================   ======================
 
 If none of these show up, you should look in the BIOS for settings like
 enable ACPI / SMBus or even USB.
diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
new file mode 100644
index 000000000000..97ca4d510816
--- /dev/null
+++ b/Documentation/i2c/busses/index.rst
@@ -0,0 +1,33 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===============
+I2C Bus Drivers
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   i2c-ali1535
+   i2c-ali1563
+   i2c-ali15x3
+   i2c-amd756
+   i2c-amd8111
+   i2c-amd-mp2
+   i2c-diolan-u2c
+   i2c-i801
+   i2c-ismt
+   i2c-mlxcpld
+   i2c-nforce2
+   i2c-nvidia-gpu
+   i2c-ocores
+   i2c-parport-light
+   i2c-parport
+   i2c-pca-isa
+   i2c-piix4
+   i2c-sis5595
+   i2c-sis630
+   i2c-sis96x
+   i2c-taos-evm
+   i2c-viapro
+   i2c-via
+   scx200_acb
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
index ce83c871fe95..8dc7c352508c 100644
--- a/Documentation/i2c/busses/scx200_acb
+++ b/Documentation/i2c/busses/scx200_acb.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver scx200_acb
+========================
 
 Author: Christer Weinigel <wingel@nano-system.com>
 
@@ -25,8 +27,11 @@ Device-specific notes
 
 The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
 If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
+parameter to your boot command line::
+
   scx200_acb.base=0x810,0x820
+
 If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
+a configuration file in /etc/modprobe.d/ instead::
+
   options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
index fbed645ccd75..69c23a3c2b1b 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface.rst
@@ -1,3 +1,7 @@
+====================
+I2C Device Interface
+====================
+
 Usually, i2c devices are controlled by a kernel driver. But it is also
 possible to access all devices on an adapter from userspace, through
 the /dev interface. You need to load module i2c-dev for this.
@@ -18,7 +22,7 @@ C example
 =========
 
 So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
+First, you need to include these two headers::
 
   #include <linux/i2c-dev.h>
   #include <i2c/smbus.h>
@@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
 Adapter numbers are assigned somewhat dynamically, so you can not
 assume much about them. They can even change from one boot to the next.
 
-Next thing, open the device file, as follows:
+Next thing, open the device file, as follows::
 
   int file;
   int adapter_nr = 2; /* probably dynamically determined */
@@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
   }
 
 When you have opened the device, you must specify with what device
-address you want to communicate:
+address you want to communicate::
 
   int addr = 0x40; /* The I2C address */
 
@@ -53,7 +57,7 @@ address you want to communicate:
 
 Well, you are all set up now. You can now use SMBus commands or plain
 I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
+the device supports them. Both are illustrated below::
 
   __u8 reg = 0x10; /* Device register to access */
   __s32 res;
@@ -100,35 +104,35 @@ Full interface description
 
 The following IOCTLs are defined:
 
-ioctl(file, I2C_SLAVE, long addr)
+``ioctl(file, I2C_SLAVE, long addr)``
   Change slave address. The address is passed in the 7 lower bits of the
   argument (except for 10 bit addresses, passed in the 10 lower bits in this
   case).
 
-ioctl(file, I2C_TENBIT, long select)
+``ioctl(file, I2C_TENBIT, long select)``
   Selects ten bit addresses if select not equals 0, selects normal 7 bit
   addresses if select equals 0. Default 0.  This request is only valid
   if the adapter has I2C_FUNC_10BIT_ADDR.
 
-ioctl(file, I2C_PEC, long select)
+``ioctl(file, I2C_PEC, long select)``
   Selects SMBus PEC (packet error checking) generation and verification
   if select not equals 0, disables if select equals 0. Default 0.
   Used only for SMBus transactions.  This request only has an effect if the
   the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
   doesn't have any effect.
 
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
-  Gets the adapter functionality and puts it in *funcs.
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
+  Gets the adapter functionality and puts it in ``*funcs``.
 
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
   Do combined read/write transaction without stop in between.
   Only valid if the adapter has I2C_FUNC_I2C.  The argument is
-  a pointer to a
+  a pointer to a::
 
-  struct i2c_rdwr_ioctl_data {
+    struct i2c_rdwr_ioctl_data {
       struct i2c_msg *msgs;  /* ptr to array of simple messages */
       int nmsgs;             /* number of messages to exchange */
-  }
+    }
 
   The msgs[] themselves contain further pointers into data buffers.
   The function will write or read data to or from that buffers depending
@@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
   The slave address and whether to use ten bit address mode has to be
   set in each message, overriding the values set with the above ioctl's.
 
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
-  If possible, use the provided i2c_smbus_* methods described below instead
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
+  If possible, use the provided ``i2c_smbus_*`` methods described below instead
   of issuing direct ioctls.
 
 You can do plain i2c transactions by using read(2) and write(2) calls.
@@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
 ioctl I2C_SLAVE before you try to access the device.
 
 You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
+for details) through the following functions::
+
   __s32 i2c_smbus_write_quick(int file, __u8 value);
   __s32 i2c_smbus_read_byte(int file);
   __s32 i2c_smbus_write_byte(int file, __u8 value);
@@ -157,6 +162,7 @@ for details) through the following functions:
   __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
   __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                    __u8 *values);
+
 All these transactions return -1 on failure; you can read errno to see
 what happened. The 'write' transactions return 0 on success; the
 'read' transactions return the read value, except for read_block, which
@@ -174,39 +180,39 @@ Implementation details
 For the interested, here's the code flow which happens inside the kernel
 when you use the /dev interface to I2C:
 
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
-
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
-
-3* Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
-
-4* Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
-
-The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
-
-5* These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+   section "C example" above.
+
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
+   driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+   respectively. You can think of i2c-dev as a generic I2C chip driver
+   that can be programmed from user-space.
+
+3) Some ioctl() calls are for administrative tasks and are handled by
+   i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+   device you want to access) and I2C_PEC (enable or disable SMBus error
+   checking on future transactions.)
+
+4) Other ioctl() calls are converted to in-kernel function calls by
+   i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+   functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+   performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+
+   The i2c-dev driver is responsible for checking all the parameters that
+   come from user-space for validity. After this point, there is no
+   difference between these calls that came from user-space through i2c-dev
+   and calls that would have been performed by kernel I2C chip drivers
+   directly. This means that I2C bus drivers don't need to implement
+   anything special to support access from user-space.
+
+5) These i2c.h functions are wrappers to the actual implementation of
+   your I2C bus driver. Each adapter must declare callback functions
+   implementing these standard calls. i2c.h:i2c_get_functionality() calls
+   i2c_adapter.algo->functionality(), while
+   i2c-core-smbus.c:i2c_smbus_xfer() calls either
+   adapter.algo->smbus_xfer() if it is implemented, or if not,
+   i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+   i2c_adapter.algo->master_xfer().
 
 After your I2C bus driver has processed these requests, execution runs
 up the call chain, with almost no processing done, except by i2c-dev to
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
index 203002054120..203002054120 100644
--- a/Documentation/i2c/DMA-considerations
+++ b/Documentation/i2c/dma-considerations.rst
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
index 0cee0fc545b4..80b14e718b52 100644
--- a/Documentation/i2c/fault-codes
+++ b/Documentation/i2c/fault-codes.rst
@@ -1,3 +1,7 @@
+=====================
+I2C/SMBUS Fault Codes
+=====================
+
 This is a summary of the most important conventions for use of fault
 codes in the I2C/SMBus stack.
 
@@ -125,4 +129,3 @@ ETIMEDOUT
         when a slave stretches clocks too far.  I2C has no such
         timeouts, but it's normal for I2C adapters to impose some
         arbitrary limits (much longer than SMBus!) too.
-
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
index 4aae8ed15873..377507c56162 100644
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality.rst
@@ -1,11 +1,15 @@
+=======================
+I2C/SMBus Functionality
+=======================
+
 INTRODUCTION
 ------------
 
-Because not every I2C or SMBus adapter implements everything in the 
+Because not every I2C or SMBus adapter implements everything in the
 I2C specifications, a client can not trust that everything it needs
 is implemented when it is given the option to attach to an adapter:
 the client needs some way to check whether an adapter has the needed
-functionality. 
+functionality.
 
 
 FUNCTIONALITY CONSTANTS
@@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
 For the most up-to-date list of functionality constants, please check
 <uapi/linux/i2c.h>!
 
+  =============================== ==============================================
   I2C_FUNC_I2C                    Plain i2c-level commands (Pure SMBus
                                   adapters typically can not do these)
   I2C_FUNC_10BIT_ADDR             Handles the 10-bit address extensions
@@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
   I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
   I2C_FUNC_SMBUS_READ_I2C_BLOCK   Handles the SMBus read_i2c_block_data command
   I2C_FUNC_SMBUS_WRITE_I2C_BLOCK  Handles the SMBus write_i2c_block_data command
+  =============================== ==============================================
 
 A few combinations of the above flags are also defined for your convenience:
 
+  =========================       ======================================
   I2C_FUNC_SMBUS_BYTE             Handles the SMBus read_byte
                                   and write_byte commands
   I2C_FUNC_SMBUS_BYTE_DATA        Handles the SMBus read_byte_data
@@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
   I2C_FUNC_SMBUS_EMUL             Handles all SMBus commands that can be
                                   emulated by a real I2C adapter (using
                                   the transparent emulation layer)
+  =========================       ======================================
 
 In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
 part of I2C_FUNC_PROTOCOL_MANGLING.
@@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
 ----------------------
 
 When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
+function callback ``functionality``. Typical implementations are given
 below.
 
 A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
+supports. This example comes from the i2c-piix4 driver::
 
   static u32 piix4_func(struct i2c_adapter *adapter)
   {
@@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
   }
 
 A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
+driver)::
 
   static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
   {
@@ -94,7 +102,7 @@ CLIENT CHECKING
 Before a client tries to attach to an adapter, or even do tests to check
 whether one of the devices it supports is present on an adapter, it should
 check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
+this is (from the lm75 driver)::
 
   static int lm75_detect(...)
   {
@@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
 to use the /dev interface. You will still have to check whether the
 functionality you need is supported, of course. This is done using
 the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
+below::
 
   int file;
   if (file = open("/dev/i2c-0", O_RDWR) < 0) {
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
index c87f416d53dd..9dca6ec7d266 100644
--- a/Documentation/i2c/gpio-fault-injection
+++ b/Documentation/i2c/gpio-fault-injection.rst
@@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
 should be detected beforehand. Also note, that SCL going down is monitored
 using interrupts, so the interrupt latency might cause the first bits to be not
 corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
+idle bus is::
 
-# echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
+  # echo 200 > lose_arbitration &
+  # i2cget -y <bus_to_test> 0x3f
 
 Panic during transfer
 =====================
@@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
 process is interruptible, though.
 
 Start of a transfer is detected by waiting for SCL going down by the master
-under test.  A good starting point for using this fault injector is:
+under test.  A good starting point for using this fault injector is::
 
-# echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
+  # echo 0 > inject_panic &
+  # i2cget -y <bus_to_test> <some_address>
 
 Note that there doesn't need to be a device listening to the address you are
 using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
index ff6d6cee6c7e..2f8fcf671b2e 100644
--- a/Documentation/i2c/i2c-protocol
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -1,8 +1,13 @@
+============
+I2C Protocol
+============
+
 This document describes the i2c protocol. Or will, when it is finished :-)
 
 Key to symbols
 ==============
 
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -15,33 +20,35 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                 for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
 
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the
+                host adapter.
+=============== =============================================================
 
 
 Simple send transaction
-======================
+=======================
 
-This corresponds to i2c_master_send.
+This corresponds to i2c_master_send::
 
   S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
 
 
 Simple receive transaction
-===========================
+==========================
 
-This corresponds to i2c_master_recv
+This corresponds to i2c_master_recv::
 
   S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 
 
 Combined transactions
-====================
+=====================
 
 This corresponds to i2c_transfer
 
 They are just like the above transactions, but instead of a stop bit P
 a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
+a byte read, followed by a byte write::
 
   S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
 
@@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
 I2C_M_NOSTART:
     In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
     point. For example, setting I2C_M_NOSTART on the second partial message
-    generates something like:
+    generates something like::
+
       S Addr Rd [A] [Data] NA Data [A] P
+
     If you set the I2C_M_NOSTART variable for the first partial message,
     we do not generate Addr, but we do generate the startbit S. This will
     probably confuse all other clients on your bus, so don't try this.
@@ -79,7 +88,8 @@ I2C_M_NOSTART:
 I2C_M_REV_DIR_ADDR:
     This toggles the Rd/Wr flag. That is, if you want to do a write, but
     need to emit an Rd instead of a Wr, or vice versa, you set this
-    flag. For example:
+    flag. For example::
+
       S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
 
 I2C_M_STOP:
diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
index a16924fbd289..a6fc6916d6bc 100644
--- a/Documentation/i2c/i2c-stub
+++ b/Documentation/i2c/i2c-stub.rst
@@ -1,6 +1,9 @@
-MODULE: i2c-stub
+========
+i2c-stub
+========
 
-DESCRIPTION:
+Description
+===========
 
 This module is a very simple fake I2C/SMBus driver.  It implements six
 types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
@@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
 return the number of bytes selected with the largest write so far.
 
 The typical use-case is like this:
+
         1. load this module
         2. use i2cset (from the i2c-tools project) to pre-load some data
         3. load the target chip driver module
@@ -36,7 +40,8 @@ The typical use-case is like this:
 There's a script named i2c-stub-from-dump in the i2c-tools package which
 can load register values automatically from a chip dump.
 
-PARAMETERS:
+Parameters
+==========
 
 int chip_addr[10]:
         The SMBus addresses to emulate chips at.
@@ -47,18 +52,15 @@ unsigned long functionality:
         value 0x1f0000 would only enable the quick, byte and byte data
         commands.
 
-u8 bank_reg[10]
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
         Optional bank settings. They tell which bits in which register
         select the active bank, as well as the range of banked registers.
 
-CAVEATS:
+Caveats
+=======
 
 If your target driver polls some byte or word waiting for it to change, the
 stub could lock it up.  Use i2cset to unlock it.
 
 If you spam it hard enough, printk can be lossy.  This module really wants
 something like relayfs.
-
diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
index f74d78b53d4d..0c1ae95f6a97 100644
--- a/Documentation/i2c/i2c-topology
+++ b/Documentation/i2c/i2c-topology.rst
@@ -1,3 +1,4 @@
+============
 I2C topology
 ============
 
@@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
    that has to be operated before the device can be accessed.
 
 Etc
+===
 
 These constructs are represented as i2c adapter trees by Linux, where
 each adapter has a parent adapter (except the root adapter) and zero or
@@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
 useful to know if a mux is mux-locked or if it is parent-locked. The
 following list was correct at the time of writing:
 
-In drivers/i2c/muxes/
+In drivers/i2c/muxes/:
+
+======================    =============================================
 i2c-arb-gpio-challenge    Parent-locked
 i2c-mux-gpio              Normally parent-locked, mux-locked iff
                           all involved gpio pins are controlled by the
@@ -52,18 +56,25 @@ i2c-mux-pinctrl           Normally parent-locked, mux-locked iff
                           all involved pinctrl devices are controlled
                           by the same i2c root adapter that they mux.
 i2c-mux-reg               Parent-locked
+======================    =============================================
+
+In drivers/iio/:
 
-In drivers/iio/
+======================    =============================================
 gyro/mpu3050              Mux-locked
 imu/inv_mpu6050/          Mux-locked
+======================    =============================================
 
-In drivers/media/
+In drivers/media/:
+
+=======================   =============================================
 dvb-frontends/lgdt3306a   Mux-locked
 dvb-frontends/m88ds3103   Parent-locked
 dvb-frontends/rtl2830     Parent-locked
 dvb-frontends/rtl2832     Mux-locked
 dvb-frontends/si2168      Mux-locked
 usb/cx231xx/              Parent-locked
+=======================   =============================================
 
 
 Mux-locked muxes
@@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
 stages of the transaction. This has the benefit that the mux driver
 may be easier and cleaner to implement, but it has some caveats.
 
+==== =====================================================================
 ML1. If you build a topology with a mux-locked mux being the parent
      of a parent-locked mux, this might break the expectation from the
      parent-locked mux that the root adapter is locked during the
@@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
      Otherwise garbage may appear on the bus as seen from devices
      behind the mux, when an unrelated i2c transfer is in flight during
      the non-i2c mux-changing operation.
+==== =====================================================================
 
 
 Mux-locked Example
 ------------------
 
+
+::
+
                    .----------.     .--------.
     .--------.     |   mux-   |-----| dev D1 |
     |  root  |--+--|  locked  |     '--------'
@@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
 __i2c_transfer), or a deadlock will follow. There are a couple of
 caveats.
 
+==== ====================================================================
 PL1. If you build a topology with a parent-locked mux being the child
      of another mux, this might break a possible assumption from the
      child mux that the root adapter is unused between its select op
@@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
      caused by these subsystems are unlocked. This can be convoluted to
      accomplish, maybe even impossible if an acceptably clean solution
      is sought.
+==== ====================================================================
 
 
 Parent-locked Example
 ---------------------
 
+::
+
                    .----------.     .--------.
     .--------.     |  parent- |-----| dev D1 |
     |  root  |--+--|  locked  |     '--------'
@@ -177,20 +197,20 @@ Parent-locked Example
 
 When there is an access to D1, this happens:
 
- 1. Someone issues an i2c-transfer to D1.
- 2. M1 locks muxes on its parent (the root adapter in this case).
- 3. M1 locks its parent adapter.
- 4. M1 calls ->select to ready the mux.
- 5. If M1 does any i2c-transfers (on this root adapter) as part of
-    its select, those transfers must be unlocked i2c-transfers so
-    that they do not deadlock the root adapter.
- 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
-    unlocked i2c-transfer, so that it does not deadlock the parent
-    adapter.
- 7. M1 calls ->deselect, if it has one.
- 8. Same rules as in step 5, but for ->deselect.
- 9. M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
+ 1.  Someone issues an i2c-transfer to D1.
+ 2.  M1 locks muxes on its parent (the root adapter in this case).
+ 3.  M1 locks its parent adapter.
+ 4.  M1 calls ->select to ready the mux.
+ 5.  If M1 does any i2c-transfers (on this root adapter) as part of
+     its select, those transfers must be unlocked i2c-transfers so
+     that they do not deadlock the root adapter.
+ 6.  M1 feeds the i2c-transfer from step 1 to the root adapter as an
+     unlocked i2c-transfer, so that it does not deadlock the parent
+     adapter.
+ 7.  M1 calls ->deselect, if it has one.
+ 8.  Same rules as in step 5, but for ->deselect.
+ 9.  M1 unlocks its parent adapter.
+ 10. M1 unlocks muxes on its parent.
 
 
 This means that accesses to both D2 and D3 are locked out for the full
@@ -203,7 +223,7 @@ Complex Examples
 Parent-locked mux as parent of parent-locked mux
 ------------------------------------------------
 
-This is a useful topology, but it can be bad.
+This is a useful topology, but it can be bad::
 
                    .----------.     .----------.     .--------.
     .--------.     |  parent- |-----|  parent- |-----| dev D1 |
@@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
 Mux-locked mux as parent of mux-locked mux
 ------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |   mux-   |-----|   mux-   |-----| dev D1 |
@@ -248,7 +268,7 @@ are still possibly interleaved.
 Mux-locked mux as parent of parent-locked mux
 ---------------------------------------------
 
-This is probably a bad topology.
+This is probably a bad topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |   mux-   |-----|  parent- |-----| dev D1 |
@@ -282,7 +302,7 @@ auto-closing, the topology is fine.
 Parent-locked mux as parent of mux-locked mux
 ---------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |  parent- |-----|   mux-   |-----| dev D1 |
@@ -306,7 +326,7 @@ adapter is locked directly.
 Two mux-locked sibling muxes
 ----------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
@@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
 Two parent-locked sibling muxes
 -------------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
@@ -354,7 +374,7 @@ out.
 Mux-locked and parent-locked sibling muxes
 ------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
new file mode 100644
index 000000000000..cd8d020f7ac5
--- /dev/null
+++ b/Documentation/i2c/index.rst
@@ -0,0 +1,37 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===================
+I2C/SMBus Subsystem
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   dev-interface
+   dma-considerations
+   fault-codes
+   functionality
+   gpio-fault-injection
+   i2c-protocol
+   i2c-stub
+   i2c-topology
+   instantiating-devices
+   old-module-parameters
+   slave-eeprom-backend
+   slave-interface
+   smbus-protocol
+   summary
+   ten-bit-addresses
+   upgrading-clients
+   writing-clients
+
+   muxes/i2c-mux-gpio
+
+   busses/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
index 345e9ea8281a..1238f1fa3382 100644
--- a/Documentation/i2c/instantiating-devices
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -1,3 +1,4 @@
+==============================
 How to instantiate I2C devices
 ==============================
 
@@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
 devices which live on this bus. This is done with an array of struct
 i2c_board_info which is registered by calling i2c_register_board_info().
 
-Example (from omap2 h4):
+Example (from omap2 h4)::
 
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
         {
                 I2C_BOARD_INFO("isp1301_omap", 0x2d),
                 .irq            = OMAP_GPIO_IRQ(125),
@@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
                 I2C_BOARD_INFO("24c01", 0x57),
                 .platform_data  = &m24c01,
         },
-};
+  };
 
-static void __init omap_h4_init(void)
-{
+  static void __init omap_h4_init(void)
+  {
         (...)
         i2c_register_board_info(1, h4_i2c_board_info,
                         ARRAY_SIZE(h4_i2c_board_info));
         (...)
-}
+  }
 
 The above code declares 3 devices on I2C bus 1, including their respective
 addresses and custom data needed by their drivers. When the I2C bus in
@@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
 This method has the same implications as method 1a. The declaration of I2C
 devices is here done via devicetree as subnodes of the master controller.
 
-Example:
+Example::
 
         i2c1: i2c@400a0000 {
                 /* ... master properties skipped ... */
@@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
 you can instantiate your I2C devices explicitly. This is done by filling
 a struct i2c_board_info and calling i2c_new_device().
 
-Example (from the sfe4001 network driver):
+Example (from the sfe4001 network driver)::
 
-static struct i2c_board_info sfe4001_hwmon_info = {
+  static struct i2c_board_info sfe4001_hwmon_info = {
         I2C_BOARD_INFO("max6647", 0x4e),
-};
+  };
 
-int sfe4001_init(struct efx_nic *efx)
-{
+  int sfe4001_init(struct efx_nic *efx)
+  {
         (...)
         efx->board_info.hwmon_client =
                 i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
 
         (...)
-}
+  }
 
 The above code instantiates 1 I2C device on the I2C bus which is on the
 network adapter in question.
@@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
 changing its design without notice). In this case, you can call
 i2c_new_probed_device() instead of i2c_new_device().
 
-Example (from the nxp OHCI driver):
+Example (from the nxp OHCI driver)::
 
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+  static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
 
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
+  static int usb_hcd_nxp_probe(struct platform_device *pdev)
+  {
         (...)
         struct i2c_adapter *i2c_adap;
         struct i2c_board_info i2c_info;
@@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
                                                    normal_i2c, NULL);
         i2c_put_adapter(i2c_adap);
         (...)
-}
+  }
 
 The above code instantiates up to 1 I2C device on the I2C bus which is on
 the OHCI adapter in question. It first tries at address 0x2c, if nothing
@@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
 drivers are loaded, and if any is found, an I2C device will be
 instantiated automatically. In order to prevent any misbehavior of this
 mechanism, the following restrictions apply:
+
 * The I2C device driver must implement the detect() method, which
   identifies a supported device by reading from arbitrary registers.
 * Only buses which are likely to have a supported device and agree to be
@@ -189,6 +191,7 @@ first.
 Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
 kernels will find out that this method 3 is essentially similar to what
 was done there. Two significant differences are:
+
 * Probing is only one way to instantiate I2C devices now, while it was the
   only way back then. Where possible, methods 1 and 2 should be preferred.
   Method 3 should only be used when there is no other way, as it can have
@@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
 segment, the address is sufficient to uniquely identify the device to be
 deleted.
 
-Example:
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+Example::
+
+  # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
 
 While this interface should only be used when in-kernel device declaration
 can't be done, there is a variety of cases where it can be helpful:
+
 * The I2C driver usually detects devices (method 3 above) but the bus
   segment your device lives on doesn't have the proper class bit set and
   thus detection doesn't trigger.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
index 893ecdfe6e43..7d27444035c3 100644
--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
@@ -1,4 +1,6 @@
+==========================
 Kernel driver i2c-mux-gpio
+==========================
 
 Author: Peter Korsgaard <peter.korsgaard@barco.com>
 
@@ -8,7 +10,7 @@ Description
 i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
 from a master I2C bus and a hardware MUX controlled through GPIO pins.
 
-E.G.:
+E.G.::
 
   ----------              ----------  Bus segment 1   - - - - -
  |          | SCL/SDA    |          |-------------- |           |
@@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
 to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
 
 E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
+controlled through 3 GPIO pins::
 
-#include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
+  #include <linux/platform_data/i2c-mux-gpio.h>
+  #include <linux/platform_device.h>
 
-static const unsigned myboard_gpiomux_gpios[] = {
+  static const unsigned myboard_gpiomux_gpios[] = {
         AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
+  };
 
-static const unsigned myboard_gpiomux_values[] = {
+  static const unsigned myboard_gpiomux_values[] = {
         0, 1, 2, 3
-};
+  };
 
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+  static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
         .parent         = 1,
         .base_nr        = 2, /* optional */
         .values         = myboard_gpiomux_values,
@@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
         .gpios          = myboard_gpiomux_gpios,
         .n_gpios        = ARRAY_SIZE(myboard_gpiomux_gpios),
         .idle           = 4, /* optional */
-};
+  };
 
-static struct platform_device myboard_i2cmux = {
+  static struct platform_device myboard_i2cmux = {
         .name           = "i2c-mux-gpio",
         .id             = 0,
         .dev            = {
                 .platform_data  = &myboard_i2cmux_data,
         },
-};
+  };
 
 If you don't know the absolute GPIO pin numbers at registration time,
 you can instead provide a chip name (.chip_name) and relative GPIO pin
diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
index 8e2b629d533c..a1939512ad66 100644
--- a/Documentation/i2c/old-module-parameters
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -1,3 +1,4 @@
+=================================================
 I2C device driver binding control from user-space
 =================================================
 
@@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
 Attaching a driver to an I2C device
 -----------------------------------
 
-Old method (module parameters):
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
+Old method (module parameters)::
+
+  # modprobe <driver> probe=1,0x2d
+  # modprobe <driver> force=1,0x2d
+  # modprobe <driver> force_<device>=1,0x2d
+
+New method (sysfs interface)::
 
-New method (sysfs interface):
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
+  # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
 
 Preventing a driver from attaching to an I2C device
 ---------------------------------------------------
 
-Old method (module parameters):
-# modprobe <driver> ignore=1,0x2f
+Old method (module parameters)::
+
+  # modprobe <driver> ignore=1,0x2f
+
+New method (sysfs interface)::
 
-New method (sysfs interface):
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# modprobe <driver>
+  # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
+  # modprobe <driver>
 
 Of course, it is important to instantiate the "dummy" device before loading
 the driver. The dummy device will be handled by i2c-core itself, preventing
diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
index 04f8d8a9b817..0b8cd83698e0 100644
--- a/Documentation/i2c/slave-eeprom-backend
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -1,3 +1,4 @@
+==============================
 Linux I2C slave eeprom backend
 ==============================
 
@@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
 
 This is a proof-of-concept backend which acts like an EEPROM on the connected
 I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
+located in sysfs::
 
         /sys/bus/i2c/devices/<device-directory>/slave-eeprom
 
 As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
 notification when another master changed the content.
-
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
index 7e2a228f21bc..c769bd6a15bf 100644
--- a/Documentation/i2c/slave-interface
+++ b/Documentation/i2c/slave-interface.rst
@@ -1,3 +1,4 @@
+=====================================
 Linux I2C slave interface description
 =====================================
 
@@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
 needed. The backend driver and the I2C bus driver communicate via events. Here
 is a small graph visualizing the data flow and the means by which data is
 transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
+use a character device, be in-kernel only, or something completely different::
 
 
               e.g. sysfs        I2C slave events        I/O registers
@@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
 is that i2c slave backends have their own address space. So, you have to add
 0x1000 to the address you would originally request. An example for
 instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
+on bus 1::
 
   # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
 
@@ -54,7 +55,7 @@ drivers and writing backends will be given.
 I2C slave events
 ----------------
 
-The bus driver sends an event to the backend using the following function:
+The bus driver sends an event to the backend using the following function::
 
         ret = i2c_slave_event(client, event, &val)
 
@@ -69,8 +70,9 @@ Event types:
 
 * I2C_SLAVE_WRITE_REQUESTED (mandatory)
 
-'val': unused
-'ret': always 0
+  'val': unused
+
+  'ret': always 0
 
 Another I2C master wants to write data to us. This event should be sent once
 our own address and the write bit was detected. The data did not arrive yet, so
@@ -79,8 +81,9 @@ to be done, though.
 
 * I2C_SLAVE_READ_REQUESTED (mandatory)
 
-'val': backend returns first byte to be sent
-'ret': always 0
+  'val': backend returns first byte to be sent
+
+  'ret': always 0
 
 Another I2C master wants to read data from us. This event should be sent once
 our own address and the read bit was detected. After returning, the bus driver
@@ -88,8 +91,9 @@ should transmit the first byte.
 
 * I2C_SLAVE_WRITE_RECEIVED (mandatory)
 
-'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+  'val': bus driver delivers received byte
+
+  'ret': 0 if the byte should be acked, some errno if the byte should be nacked
 
 Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
 is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
@@ -97,8 +101,9 @@ should be nacked.
 
 * I2C_SLAVE_READ_PROCESSED (mandatory)
 
-'val': backend returns next byte to be sent
-'ret': always 0
+  'val': backend returns next byte to be sent
+
+  'ret': always 0
 
 The bus driver requests the next byte to be sent to another I2C master in
 'val'. Important: This does not mean that the previous byte has been acked, it
@@ -111,8 +116,9 @@ your backend, though.
 
 * I2C_SLAVE_STOP (mandatory)
 
-'val': unused
-'ret': always 0
+  'val': unused
+
+  'ret': always 0
 
 A stop condition was received. This can happen anytime and the backend should
 reset its state machine for I2C transfers to be able to receive new requests.
@@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers:
 * A master can send STOP at any time. For partially transferred buffers, this
   means additional code to handle this exception. Such code tends to be
   error-prone.
-
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
index 092d474f5843..e30eb1d274c6 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -1,3 +1,4 @@
+======================
 SMBus Protocol Summary
 ======================
 
@@ -27,17 +28,18 @@ Each transaction type corresponds to a functionality flag. Before calling a
 transaction function, a device driver should always check (just once) for
 the corresponding functionality flag to ensure that the underlying I2C
 adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
+<file:Documentation/i2c/functionality.rst> for the details.
 
 
 Key to symbols
 ==============
 
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit. 
-Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to 
+A, NA (1 bit) : Accept and reverse accept bit.
+Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
 Comm  (8 bits): Command byte, a data byte which often selects a register on
                 the device.
@@ -45,15 +47,17 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                 for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
 
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the host
+                adapter.
+=============== =============================================================
 
 
 SMBus Quick Command
 ===================
 
-This sends a single bit to the device, at the place of the Rd/Wr bit.
+This sends a single bit to the device, at the place of the Rd/Wr bit::
 
-A Addr Rd/Wr [A] P
+  A Addr Rd/Wr [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_QUICK
 
@@ -64,9 +68,9 @@ SMBus Receive Byte:  i2c_smbus_read_byte()
 This reads a single byte from a device, without specifying a device
 register. Some devices are so simple that this interface is enough; for
 others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
+the previous SMBus command::
 
-S Addr Rd [A] [Data] NA P
+  S Addr Rd [A] [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
 
@@ -77,7 +81,9 @@ SMBus Send Byte:  i2c_smbus_write_byte()
 This operation is the reverse of Receive Byte: it sends a single byte
 to a device.  See Receive Byte for more information.
 
-S Addr Wr [A] Data [A] P
+::
+
+  S Addr Wr [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
 
@@ -86,9 +92,9 @@ SMBus Read Byte:  i2c_smbus_read_byte_data()
 ============================================
 
 This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
+The register is specified through the Comm byte::
 
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
 
@@ -98,9 +104,9 @@ SMBus Read Word:  i2c_smbus_read_word_data()
 
 This operation is very like Read Byte; again, data is read from a
 device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
+byte. But this time, the data is a complete word (16 bits)::
 
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
 
@@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
 register is specified through the Comm byte. This is the opposite of
 the Read Byte operation.
 
-S Addr Wr [A] Comm [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
 
@@ -126,9 +134,9 @@ SMBus Write Word:  i2c_smbus_write_word_data()
 
 This is the opposite of the Read Word operation. 16 bits
 of data is written to a device, to the designated register that is
-specified through the Comm byte. 
+specified through the Comm byte.::
 
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
 
@@ -141,10 +149,10 @@ SMBus Process Call:
 ===================
 
 This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
+16 bits of data to it, and reads 16 bits of data in return::
 
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] 
-                             S Addr Rd [A] [DataLow] A [DataHigh] NA P
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
+                               S Addr Rd [A] [DataLow] A [DataHigh] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
 
@@ -152,12 +160,14 @@ Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
 SMBus Block Read:  i2c_smbus_read_block_data()
 ==============================================
 
-This command reads a block of up to 32 bytes from a device, from a 
+This command reads a block of up to 32 bytes from a device, from a
 designated register that is specified through the Comm byte. The amount
 of data is specified by the device in the Count byte.
 
-S Addr Wr [A] Comm [A] 
-           S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
+::
+
+  S Addr Wr [A] Comm [A]
+             S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
 
@@ -165,11 +175,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
 SMBus Block Write:  i2c_smbus_write_block_data()
 ================================================
 
-The opposite of the Block Read command, this writes up to 32 bytes to 
+The opposite of the Block Read command, this writes up to 32 bytes to
 a device, to a designated register that is specified through the
 Comm byte. The amount of data is specified in the Count byte.
 
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
 
@@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
 Revision 2.0 of the specification.
 
 This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
 
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
-                             S Addr Rd [A] [Count] A [Data] ... A P
+  S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+                               S Addr Rd [A] [Count] A [Data] ... A P
 
 Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
 
@@ -197,9 +209,12 @@ SMBus host acting as a slave.
 It is the same form as Write Word, with the command code replaced by the
 alerting device's address.
 
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+::
+
+  [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
 
 This is implemented in the following way in the Linux kernel:
+
 * I2C bus drivers which support SMBus Host Notify should report
   I2C_FUNC_SMBUS_HOST_NOTIFY.
 * I2C bus drivers trigger SMBus Host Notify by a call to
@@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
 to know which slave triggered the interrupt.
 
 This is implemented the following way in the Linux kernel:
+
 * I2C bus drivers which support SMBus alert should call
   i2c_setup_smbus_alert() to setup SMBus alert support.
 * I2C drivers for devices which can trigger SMBus alerts should implement
@@ -261,11 +277,11 @@ but the SMBus layer places a limit of 32 bytes.
 I2C Block Read:  i2c_smbus_read_i2c_block_data()
 ================================================
 
-This command reads a block of bytes from a device, from a 
-designated register that is specified through the Comm byte.
+This command reads a block of bytes from a device, from a
+designated register that is specified through the Comm byte::
 
-S Addr Wr [A] Comm [A] 
-           S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+  S Addr Wr [A] Comm [A]
+             S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
 
@@ -273,11 +289,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
 I2C Block Write:  i2c_smbus_write_i2c_block_data()
 ==================================================
 
-The opposite of the Block Read command, this writes bytes to 
+The opposite of the Block Read command, this writes bytes to
 a device, to a designated register that is specified through the
 Comm byte. Note that command lengths of 0, 2, or more bytes are
 supported as they are indistinguishable from data.
 
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
index 809541ab352f..3a24eac17375 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary.rst
@@ -1,7 +1,8 @@
+=============
 I2C and SMBus
 =============
 
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a 
+I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
 slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
 extension (3.4 MHz).  It provides an inexpensive bus for connecting many
 types of devices with infrequent or low bandwidth communications needs.
@@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-When we talk about I2C, we use the following terms:
+When we talk about I2C, we use the following terms::
+
   Bus    -> Algorithm
             Adapter
   Device -> Driver
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
index 7b2d11e53a49..5c765aff16d5 100644
--- a/Documentation/i2c/ten-bit-addresses
+++ b/Documentation/i2c/ten-bit-addresses.rst
@@ -1,3 +1,7 @@
+=====================
+I2C Ten-bit Addresses
+=====================
+
 The I2C protocol knows about two kinds of device addresses: normal 7 bit
 addresses, and an extended set of 10 bit addresses. The sets of addresses
 do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
@@ -12,6 +16,7 @@ See the I2C specification for the details.
 
 The current 10 bit address support is minimal. It should work, however
 you can expect some problems along the way:
+
 * Not all bus drivers support 10-bit addresses. Some don't because the
   hardware doesn't support them (SMBus doesn't require 10-bit address
   support for example), some don't because nobody bothered adding the
diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
index 96392cc5b5c7..27d29032c138 100644
--- a/Documentation/i2c/upgrading-clients
+++ b/Documentation/i2c/upgrading-clients.rst
@@ -1,3 +1,4 @@
+=================================================
 Upgrading I2C Drivers to the new 2.6 Driver Model
 =================================================
 
@@ -13,21 +14,22 @@ the old to the new new binding methods.
 Example old-style driver
 ------------------------
 
+::
 
-struct example_state {
+  struct example_state {
         struct i2c_client       client;
         ....
-};
+  };
 
-static struct i2c_driver example_driver;
+  static struct i2c_driver example_driver;
 
-static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  static unsigned short ignore[] = { I2C_CLIENT_END };
+  static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
 
-I2C_CLIENT_INSMOD;
+  I2C_CLIENT_INSMOD;
 
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
+  static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  {
         struct example_state *state;
         struct device *dev = &adap->dev;  /* to use for dev_ reports */
         int ret;
@@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
         dev_info(dev, "example client created\n");
 
         return 0;
-}
+  }
 
-static int example_detach(struct i2c_client *client)
-{
+  static int example_detach(struct i2c_client *client)
+  {
         struct example_state *state = i2c_get_clientdata(client);
 
         i2c_detach_client(client);
         kfree(state);
         return 0;
-}
+  }
 
-static int example_attach_adapter(struct i2c_adapter *adap)
-{
+  static int example_attach_adapter(struct i2c_adapter *adap)
+  {
         return i2c_probe(adap, &addr_data, example_attach);
-}
+  }
 
-static struct i2c_driver example_driver = {
-        .driver         = {
+  static struct i2c_driver example_driver = {
+        .driver         = {
                 .owner          = THIS_MODULE,
                 .name           = "example",
                 .pm             = &example_pm_ops,
         },
         .attach_adapter = example_attach_adapter,
         .detach_client  = example_detach,
-};
+  };
 
 
 Updating the client
@@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
 devices and their associated address supplied by the code registering
 the busses. This means that the driver .attach_adapter and
 .detach_client methods can be removed, along with the addr_data,
-as follows:
+as follows::
 
-- static struct i2c_driver example_driver;
+  - static struct i2c_driver example_driver;
 
-- static unsigned short ignore[] = { I2C_CLIENT_END };
-- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  - static unsigned short ignore[] = { I2C_CLIENT_END };
+  - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
 
-- I2C_CLIENT_INSMOD;
+  - I2C_CLIENT_INSMOD;
 
-- static int example_attach_adapter(struct i2c_adapter *adap)
-- {
--       return i2c_probe(adap, &addr_data, example_attach);
-- }
+  - static int example_attach_adapter(struct i2c_adapter *adap)
+  - {
+  -     return i2c_probe(adap, &addr_data, example_attach);
+  - }
 
- static struct i2c_driver example_driver = {
--       .attach_adapter = example_attach_adapter,
--       .detach_client  = example_detach,
- }
+    static struct i2c_driver example_driver = {
+  -     .attach_adapter = example_attach_adapter,
+  -     .detach_client  = example_detach,
+    }
 
-Add the probe and remove methods to the i2c_driver, as so:
+Add the probe and remove methods to the i2c_driver, as so::
 
- static struct i2c_driver example_driver = {
-+       .probe          = example_probe,
-+       .remove         = example_remove,
- }
+   static struct i2c_driver example_driver = {
+  +     .probe          = example_probe,
+  +     .remove         = example_remove,
+   }
 
 Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
+which include the i2c_client that it will be working with::
 
-- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
-+                          const struct i2c_device_id *id)
+  - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  + static int example_probe(struct i2c_client *client,
+  +                        const struct i2c_device_id *id)
 
 Change the name of example_attach to example_probe to align it with the
 i2c_driver entry names. The rest of the probe routine will now need to be
@@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use.
 
 The necessary client fields have already been setup before
 the probe function is called, so the following client setup
-can be removed:
+can be removed::
 
--       example->client.addr    = addr;
--       example->client.flags   = 0;
--       example->client.adapter = adap;
--
--       strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+  -     example->client.addr    = addr;
+  -     example->client.flags   = 0;
+  -     example->client.adapter = adap;
+  -
+  -     strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
 
-The i2c_set_clientdata is now:
+The i2c_set_clientdata is now::
 
--       i2c_set_clientdata(&state->client, state);
-+       i2c_set_clientdata(client, state);
+  -     i2c_set_clientdata(&state->client, state);
+  +     i2c_set_clientdata(client, state);
 
 The call to i2c_attach_client is no longer needed, if the probe
 routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
+attached by the core. Change the probe routine as so::
 
--       ret = i2c_attach_client(&state->i2c_client);
--       if (ret < 0) {
--               dev_err(dev, "failed to attach client\n");
--               kfree(state);
--               return ret;
--       }
+  -     ret = i2c_attach_client(&state->i2c_client);
+  -     if (ret < 0) {
+  -             dev_err(dev, "failed to attach client\n");
+  -             kfree(state);
+  -             return ret;
+  -     }
 
 
 Remove the storage of 'struct i2c_client' from the 'struct example_state'
 as we are provided with the i2c_client in our example_probe. Instead we
 store a pointer to it for when it is needed.
 
-struct example_state {
--       struct i2c_client       client;
-+       struct i2c_client       *client;
+::
+
+  struct example_state {
+  -     struct i2c_client       client;
+  +     struct i2c_client       *client;
 
-the new i2c client as so:
+the new i2c client as so::
 
--       struct device *dev = &adap->dev;  /* to use for dev_ reports */
-+       struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
+  -     struct device *dev = &adap->dev;  /* to use for dev_ reports */
+  +     struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
 
 And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
+longer needs to register a new client structure with the core::
 
--       dev = &state->i2c_client.dev;
+  -     dev = &state->i2c_client.dev;
 
 In the probe routine, ensure that the new state has the client stored
-in it:
+in it::
 
-static int example_probe(struct i2c_client *i2c_client,
+  static int example_probe(struct i2c_client *i2c_client,
                          const struct i2c_device_id *id)
-{
+  {
         struct example_state *state;
-        struct device *dev = &i2c_client->dev;
+        struct device *dev = &i2c_client->dev;
         int ret;
 
         state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
@@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
                 return -ENOMEM;
         }
 
-+       state->client = i2c_client;
+  +     state->client = i2c_client;
 
 Update the detach method, by changing the name to _remove and
 to delete the i2c_detach_client call. It is possible that you
 can also remove the ret variable as it is not needed for any
 of the core functions.
 
-- static int example_detach(struct i2c_client *client)
-+ static int example_remove(struct i2c_client *client)
-{
+::
+
+  - static int example_detach(struct i2c_client *client)
+  + static int example_remove(struct i2c_client *client)
+  {
         struct example_state *state = i2c_get_clientdata(client);
 
--       i2c_detach_client(client);
+  -     i2c_detach_client(client);
 
 And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
+and other utilities::
 
-+ struct i2c_device_id example_idtable[] = {
-+       { "example", 0 },
-+       { }
-+};
-+
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
+  + struct i2c_device_id example_idtable[] = {
+  +       { "example", 0 },
+  +       { }
+  +};
+  +
+  +MODULE_DEVICE_TABLE(i2c, example_idtable);
 
-static struct i2c_driver example_driver = {
-        .driver         = {
+  static struct i2c_driver example_driver = {
+        .driver         = {
                 .owner          = THIS_MODULE,
                 .name           = "example",
         },
-+       .id_table       = example_ids,
+  +     .id_table       = example_ids,
 
 
-Our driver should now look like this:
+Our driver should now look like this::
 
-struct example_state {
+  struct example_state {
         struct i2c_client       *client;
         ....
-};
+  };
 
-static int example_probe(struct i2c_client *client,
-                         const struct i2c_device_id *id)
-{
+  static int example_probe(struct i2c_client *client,
+                         const struct i2c_device_id *id)
+  {
         struct example_state *state;
         struct device *dev = &client->dev;
 
@@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client,
         dev_info(dev, "example client created\n");
 
         return 0;
-}
+  }
 
-static int example_remove(struct i2c_client *client)
-{
+  static int example_remove(struct i2c_client *client)
+  {
         struct example_state *state = i2c_get_clientdata(client);
 
         kfree(state);
         return 0;
-}
+  }
 
-static struct i2c_device_id example_idtable[] = {
+  static struct i2c_device_id example_idtable[] = {
         { "example", 0 },
         { }
-};
+  };
 
-MODULE_DEVICE_TABLE(i2c, example_idtable);
+  MODULE_DEVICE_TABLE(i2c, example_idtable);
 
-static struct i2c_driver example_driver = {
-        .driver         = {
+  static struct i2c_driver example_driver = {
+        .driver         = {
                 .owner          = THIS_MODULE,
                 .name           = "example",
                 .pm             = &example_pm_ops,
@@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
         .id_table       = example_idtable,
         .probe          = example_probe,
         .remove         = example_remove,
-};
+  };
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
index a755b141fa4a..dddf0a14ab7c 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients.rst
@@ -1,3 +1,7 @@
+===================
+Writing I2C Clients
+===================
+
 This is a small guide for those who want to write kernel drivers for I2C
 or SMBus devices, using Linux as the protocol host/master (not slave).
 
@@ -12,7 +16,7 @@ General remarks
 Try to keep the kernel namespace as clean as possible. The best way to
 do this is to use a unique prefix for all global symbols. This is
 especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
 tutorial.
 
 
@@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
 provide.  A client structure holds device-specific information like the
 driver model device node, and its I2C address.
 
-static struct i2c_device_id foo_idtable[] = {
+::
+
+  static struct i2c_device_id foo_idtable[] = {
         { "foo", my_id_for_foo },
         { "bar", my_id_for_bar },
         { }
-};
+  };
 
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
+  MODULE_DEVICE_TABLE(i2c, foo_idtable);
 
-static struct i2c_driver foo_driver = {
+  static struct i2c_driver foo_driver = {
         .driver = {
                 .name   = "foo",
                 .pm     = &foo_pm_ops,  /* optional */
@@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
 
         .shutdown       = foo_shutdown, /* optional */
         .command        = foo_command,  /* optional, deprecated */
-}
+  }
 
 The name field is the driver name, and must not contain spaces.  It
 should match the module name (if the driver can be compiled as a module),
@@ -64,16 +70,18 @@ below.
 Extra client data
 =================
 
-Each client structure has a special `data' field that can point to any
+Each client structure has a special ``data`` field that can point to any
 structure at all.  You should use this to keep device-specific data.
 
+::
+
         /* store the value */
         void i2c_set_clientdata(struct i2c_client *client, void *data);
 
         /* retrieve the value */
         void *i2c_get_clientdata(const struct i2c_client *client);
 
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
 to NULL in remove() or if probe() failed anymore. The i2c-core does this
 automatically on these occasions. Those are also the only times the core will
 touch this field.
@@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
 be encapsulated.
 
 The below functions are simple examples, and should not be copied
-literally.
+literally::
 
-int foo_read_value(struct i2c_client *client, u8 reg)
-{
+  int foo_read_value(struct i2c_client *client, u8 reg)
+  {
         if (reg < 0x10) /* byte-sized register */
                 return i2c_smbus_read_byte_data(client, reg);
         else            /* word-sized register */
                 return i2c_smbus_read_word_data(client, reg);
-}
+  }
 
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
+  int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+  {
         if (reg == 0x10)        /* Impossible to write - driver error! */
                 return -EINVAL;
         else if (reg < 0x10)    /* byte-sized register */
                 return i2c_smbus_write_byte_data(client, reg, value);
         else                    /* word-sized register */
                 return i2c_smbus_write_word_data(client, reg, value);
-}
+  }
 
 
 Probing and attaching
@@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
 kind of driver in Linux:  they provide a probe() method to bind to
 those devices, and a remove() method to unbind.
 
+::
+
         static int foo_probe(struct i2c_client *client,
                              const struct i2c_device_id *id);
         static int foo_remove(struct i2c_client *client);
@@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
 you have to do some initializing. Fortunately, just registering the
 driver module is usually enough.
 
-static int __init foo_init(void)
-{
+::
+
+  static int __init foo_init(void)
+  {
         return i2c_add_driver(&foo_driver);
-}
-module_init(foo_init);
+  }
+  module_init(foo_init);
 
-static void __exit foo_cleanup(void)
-{
+  static void __exit foo_cleanup(void)
+  {
         i2c_del_driver(&foo_driver);
-}
-module_exit(foo_cleanup);
+  }
+  module_exit(foo_cleanup);
 
-The module_i2c_driver() macro can be used to reduce above code.
+  The module_i2c_driver() macro can be used to reduce above code.
 
-module_i2c_driver(foo_driver);
+  module_i2c_driver(foo_driver);
 
-Note that some functions are marked by `__init'.  These functions can
+Note that some functions are marked by ``__init``.  These functions can
 be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
 the code is built into the kernel, as they would never be called.
 
 
 Driver Information
 ==================
 
-/* Substitute your own name and email address */
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+::
 
-/* a few non-GPL license types are also allowed */
-MODULE_LICENSE("GPL");
+  /* Substitute your own name and email address */
+  MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+  MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+  /* a few non-GPL license types are also allowed */
+  MODULE_LICENSE("GPL");
 
 
 Power Management
@@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
 Plain I2C communication
 -----------------------
 
+::
+
         int i2c_master_send(struct i2c_client *client, const char *buf,
                             int count);
         int i2c_master_recv(struct i2c_client *client, char *buf, int count);
@@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
 less than 64k since msg.len is u16.) Returned is the actual number of bytes
 read/written.
 
+::
+
         int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
                          int num);
 
@@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
 for each message the client address, the number of bytes of the message
 and the message data itself.
 
-You can read the file `i2c-protocol' for more information about the
+You can read the file ``i2c-protocol`` for more information about the
 actual I2C protocol.
 
 
 SMBus communication
 -------------------
 
+::
+
         s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
                            unsigned short flags, char read_write, u8 command,
                            int size, union i2c_smbus_data *data);
@@ -357,6 +377,8 @@ SMBus communication
 This is the generic SMBus function. All functions below are implemented
 in terms of it. Never use this function directly!
 
+::
+
         s32 i2c_smbus_read_byte(struct i2c_client *client);
         s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
         s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
@@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
                                            const u8 *values);
 
 These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
+be added back later if needed::
 
         s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
         s32 i2c_smbus_process_call(struct i2c_client *client,
@@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
 value, except for block transactions, which return the number of values
 read. The block buffers need not be longer than 32 bytes.
 
-You can read the file `smbus-protocol' for more information about the
+You can read the file ``smbus-protocol`` for more information about the
 actual SMBus protocol.
 
 
@@ -397,7 +419,7 @@ General purpose routines
 ========================
 
 Below all general purpose routines are listed, that were not mentioned
-before.
+before::
 
         /* Return the adapter number for a specific adapter */
         int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2df5a3da563c..b5fd87e7dbee 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,7 +104,9 @@ needed).
    fb/index
    fpga/index
    hid/index
+   i2c/index
    iio/index
+   isdn/index
    infiniband/index
    leds/index
    media/index
@@ -114,8 +116,10 @@ needed).
    power/index
    target/index
    timers/index
+   spi/index
+   w1/index
    watchdog/index
-   virtual/index
+   virt/index
    input/index
    hwmon/index
    gpu/index
@@ -146,6 +150,10 @@ implementation.
    ia64/index
    m68k/index
    powerpc/index
+   mips/index
+   nios2/nios2
+   openrisc/index
+   parisc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
index 6be70342e709..307fe22d9668 100644
--- a/Documentation/input/multi-touch-protocol.rst
+++ b/Documentation/input/multi-touch-protocol.rst
@@ -23,7 +23,7 @@ devices capable of tracking identifiable contacts (type B), the protocol
 describes how to send updates for individual contacts via event slots.
 
 .. note::
-   MT potocol type A is obsolete, all kernel drivers have been
+   MT protocol type A is obsolete, all kernel drivers have been
    converted to use type B.
 
 Protocol Usage
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
 
 The driver provides a kernel capi2.0 Interface (kernelcapi) and
 on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
 t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
 
 Currently supported cards:
-        B1 ISA (all versions)
-        B1 PCI
-        T1/T1B (HEMA card)
-        M1
-        M2
-        B1 PCMCIA
+
+        - B1 ISA (all versions)
+        - B1 PCI
+        - T1/T1B (HEMA card)
+        - M1
+        - M2
+        - B1 PCMCIA
 
 Installing
 ----------
 
 You need at least /dev/capi20 to load the firmware.
 
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+    mknod /dev/capi20 c 68 0
+    mknod /dev/capi20.00 c 68 1
+    mknod /dev/capi20.01 c 68 2
+    .
+    .
+    .
+    mknod /dev/capi20.19 c 68 20
 
 Running
 -------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
 AVM GmbH provides several t4-files for the different D-channel
 protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
 
-if you configure as modules load the modules this way:
+if you configure as modules load the modules this way::
+
+    insmod /lib/modules/current/misc/capiutil.o
+    insmod /lib/modules/current/misc/b1.o
+    insmod /lib/modules/current/misc/kernelcapi.o
+    insmod /lib/modules/current/misc/capidrv.o
+    insmod /lib/modules/current/misc/capi.o
 
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
+if you have an B1-PCI card load the module b1pci.o::
 
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+    insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/t1.t4 1
 
 if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
 before you insert the card.
 
 Leased Lines with B1
 --------------------
+
 Init card and load firmware.
+
 For an D64S use "FV: 1" as phone number
+
 For an D64S2 use "FV: 1" and "FV: 2" for multilink
 or "FV: 1,2" to use CAPI channel bundling.
 
 /proc-Interface
 -----------------
 
-/proc/capi:
+/proc/capi::
+
   dr-xr-xr-x   2 root     root            0 Jul  1 14:03 .
   dr-xr-xr-x  82 root     root            0 Jun 30 19:08 ..
   -r--r--r--   1 root     root            0 Jul  1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
 
 /proc/capi/applications:
    applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
-        level3cnt: capi_register parameter
-        datablkcnt: capi_register parameter
-        ncci-cnt: current number of nccis (connections)
-        recvqueuelen: number of messages on receive queue
-   for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+        level3cnt:
+            capi_register parameter
+        datablkcnt:
+            capi_register parameter
+        ncci-cnt:
+            current number of nccis (connections)
+        recvqueuelen:
+            number of messages on receive queue
+
+   for example::
+
+        1 -2 16 2048 1 0
+        2 2 7 2048 1 0
 
 /proc/capi/applstats:
    applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
-        recvctlmsg: capi messages received without DATA_B3_IND
-        recvdatamsg: capi DATA_B3_IND received
-        sentctlmsg: capi messages sent without DATA_B3_REQ
-        sentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2057 1699 1721 1699
+        recvctlmsg:
+            capi messages received without DATA_B3_IND
+        recvdatamsg:
+            capi DATA_B3_IND received
+        sentctlmsg:
+            capi messages sent without DATA_B3_REQ
+        sentdatamsg:
+            capi DATA_B3_REQ sent
+
+   for example::
+
+        1 2057 1699 1721 1699
 
 /proc/capi/capi20: statistics of capi.o (/dev/capi20)
     minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-        minor: minor device number of capi device
-        nopen: number of calls to devices open
-        nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
-        nrecvctlmsg: capi messages received without DATA_B3_IND
-        nrecvdatamsg: capi DATA_B3_IND received
-        nsentctlmsg: capi messages sent without DATA_B3_REQ
-        nsentdatamsg: capi DATA_B3_REQ sent
-
-   for example:
-1 2 18 0 16 2
+        minor:
+            minor device number of capi device
+        nopen:
+            number of calls to devices open
+        nrecvdropmsg:
+            capi messages dropped (messages in recvqueue in close)
+        nrecvctlmsg:
+            capi messages received without DATA_B3_IND
+        nrecvdatamsg:
+            capi DATA_B3_IND received
+        nsentctlmsg:
+            capi messages sent without DATA_B3_REQ
+        nsentdatamsg:
+            capi DATA_B3_REQ sent
+
+   for example::
+
+        1 2 18 0 16 2
 
 /proc/capi/capidrv: statistics of capidrv.o (capi messages)
     nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-        nrecvctlmsg: capi messages received without DATA_B3_IND
-        nrecvdatamsg: capi DATA_B3_IND received
-        nsentctlmsg: capi messages sent without DATA_B3_REQ
-        nsentdatamsg: capi DATA_B3_REQ sent
+        nrecvctlmsg:
+            capi messages received without DATA_B3_IND
+        nrecvdatamsg:
+            capi DATA_B3_IND received
+        nsentctlmsg:
+            capi messages sent without DATA_B3_REQ
+        nsentdatamsg:
+            capi DATA_B3_REQ sent
+
    for example:
-2780 2226 2256 2226
+        2780 2226 2256 2226
 
 /proc/capi/controller:
    controller drivername state cardname   controllerinfo
-   for example:
-1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
-2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
-3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
+
+   for example::
+
+        1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
+        2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
+        3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
 
 /proc/capi/contrstats:
     controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-        nrecvctlmsg: capi messages received without DATA_B3_IND
-        nrecvdatamsg: capi DATA_B3_IND received
-        nsentctlmsg: capi messages sent without DATA_B3_REQ
-        nsentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+        nrecvctlmsg:
+            capi messages received without DATA_B3_IND
+        nrecvdatamsg:
+            capi DATA_B3_IND received
+        nsentctlmsg:
+            capi messages sent without DATA_B3_REQ
+        nsentdatamsg:
+            capi DATA_B3_REQ sent
+
+   for example::
+
+        1 2845 2272 2310 2274
+        2 2 0 2 0
+        3 2 0 2 0
 
 /proc/capi/driver:
    drivername ncontroller
-   for example:
-b1pci                            1
-t1isa                            1
-b1pcmcia                         1
-b1isa                            0
+
+   for example::
+
+        b1pci                            1
+        t1isa                            1
+        b1pcmcia                         1
+        b1isa                            0
 
 /proc/capi/ncci:
    apllid ncci winsize sendwindow
-   for example:
-1 0x10101 8 0
+
+   for example::
+
+        1 0x10101 8 0
 
 /proc/capi/users: kernelmodules that use the kernelcapi.
    name
-   for example:
-capidrv
-capi20
+
+   for example::
+
+        capidrv
+        capi20
 
 Questions
 ---------
+
 Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
 linux-avmb1@calle.in-berlin.de mailing list by sending
 a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
 German documentation and several scripts can be found at
 ftp://ftp.avm.de/cardware/b1/linux/
 
-Bugs 
+Bugs
 ----
-If you find any please let me know. 
+
+If you find any please let me know.
 
 Enjoy,
 
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
 
 I want to thank all who contributed to this project and especially to:
 (in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
   For creating and maintaining the FAQ.
 
 Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
-  For creating the FAQ, and the leafsite HOWTO. 
+  For creating the FAQ, and the leafsite HOWTO.
 
 Michael 'Ghandi' Herold (michael@abadonna.franken.de)
   For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
 Thomas Uhl (uhl@think.de)
   For distributing the cards.
   For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
 GigaSet 307x Device Driver
 ==========================
 
 1.   Requirements
-     ------------
+=================
+
 1.1. Hardware
-     --------
+-------------
+
      This driver supports the connection of the Gigaset 307x/417x family of
      ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
      connection. The following devices are reported to be compatible:
 
      Bases:
-        Siemens Gigaset 3070/3075 isdn
-        Siemens Gigaset 4170/4175 isdn
-        Siemens Gigaset SX205/255
-        Siemens Gigaset SX353
-        T-Com Sinus 45 [AB] isdn
-        T-Com Sinus 721X[A] [SE]
-        Vox Chicago 390 ISDN (KPN Telecom)
+       - Siemens Gigaset 3070/3075 isdn
+       - Siemens Gigaset 4170/4175 isdn
+       - Siemens Gigaset SX205/255
+       - Siemens Gigaset SX353
+       - T-Com Sinus 45 [AB] isdn
+       - T-Com Sinus 721X[A] [SE]
+       - Vox Chicago 390 ISDN (KPN Telecom)
 
      RS232 data boxes:
-        Siemens Gigaset M101 Data
-        T-Com Sinus 45 Data 1
+       - Siemens Gigaset M101 Data
+       - T-Com Sinus 45 Data 1
 
      USB data boxes:
-        Siemens Gigaset M105 Data
-        Siemens Gigaset USB Adapter DECT
-        T-Com Sinus 45 Data 2
-        T-Com Sinus 721 data
-        Chicago 390 USB (KPN)
+       - Siemens Gigaset M105 Data
+       - Siemens Gigaset USB Adapter DECT
+       - T-Com Sinus 45 Data 2
+       - T-Com Sinus 721 data
+       - Chicago 390 USB (KPN)
 
      See also http://www.erbze.info/sinus_gigaset.htm
        (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
      with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
      If you have another device that works with our driver, please let us know.
 
-     Chances of getting an USB device to work are good if the output of
-        lsusb
-     at the command line contains one of the following:
-        ID 0681:0001
-        ID 0681:0002
-        ID 0681:0009
-        ID 0681:0021
-        ID 0681:0022
+     Chances of getting an USB device to work are good if the output of::
+
+        lsusb
+
+     at the command line contains one of the following::
+
+        ID 0681:0001
+        ID 0681:0002
+        ID 0681:0009
+        ID 0681:0021
+        ID 0681:0022
 
 1.2. Software
-     --------
+-------------
+
      The driver works with the Kernel CAPI subsystem and can be used with any
      software which is able to use CAPI 2.0 for ISDN connections (voice or data).
 
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
 
 
 2.   How to use the driver
-     ---------------------
+==========================
+
 2.1. Modules
-     -------
+------------
+
      For the devices to work, the proper kernel modules have to be loaded.
      This normally happens automatically when the system detects the USB
      device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
      which uses the regular serial port driver to access the device, and must
      therefore be attached to the serial device to which the M101 is connected.
      The ldattach(8) command (included in util-linux-ng release 2.14 or later)
-     can be used for that purpose, for example:
+     can be used for that purpose, for example::
+
         ldattach GIGASET_M101 /dev/ttyS1
+
      This will open the device file, attach the line discipline to it, and
      then sleep in the background, keeping the device open so that the line
      discipline remains active. To deactivate it, kill the daemon, for example
-     with
+     with::
+
         killall ldattach
+
      before disconnecting the device. To have this happen automatically at
      system startup/shutdown on an LSB compatible system, create and activate
      an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
 
      The modules accept the following parameters:
 
-        Module          Parameter  Meaning
+        =============== ========== ==========================================
+        Module          Parameter  Meaning
 
-        gigaset         debug      debug level (see section 3.2.)
+        gigaset         debug      debug level (see section 3.2.)
 
                         startmode  initial operation mode (see section 2.5.):
         bas_gigaset )              1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
         usb_gigaset )   cidmode    initial Call-ID mode setting (see section
                                    2.5.): 1=on (default), 0=off
 
+        =============== ========== ==========================================
+
      Depending on your distribution you may want to create a separate module
      configuration file like /etc/modprobe.d/gigaset.conf for these.
 
 2.2. Device nodes for user space programs
-     ------------------------------------
+-----------------------------------------
+
      The device can be accessed from user space (eg. by the user space tools
      mentioned in 1.2.) through the device nodes:
 
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
 
      You can also set a "default device" for the user space tools to use when
      no device node is given as parameter, by creating a symlink /dev/ttyG to
-     one of them, eg.:
+     one of them, eg.::
 
         ln -s /dev/ttyGB0 /dev/ttyG
 
      The devices accept the following device specific ioctl calls
      (defined in gigaset_dev.h):
 
-     ioctl(int fd, GIGASET_REDIR, int *cmd);
+     ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
      If cmd==1, the device is set to be controlled exclusively through the
      character device node; access from the ISDN subsystem is blocked.
+
      If cmd==0, the device is set to be used from the ISDN subsystem and does
      not communicate through the character device node.
 
-     ioctl(int fd, GIGASET_CONFIG, int *cmd);
+     ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
      (ser_gigaset and usb_gigaset only)
+
      If cmd==1, the device is set to adapter configuration mode where commands
      are interpreted by the M10x DECT adapter itself instead of being
      forwarded to the base station. In this mode, the device accepts the
      commands described in Siemens document "AT-Kommando Alignment M10x Data"
      for setting the operation mode, associating with a base station and
      querying parameters like field strengh and signal quality.
+
      Note that there is no ioctl command for leaving adapter configuration
      mode and returning to regular operation. In order to leave adapter
      configuration mode, write the command ATO to the device.
 
-     ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+     ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
      (usb_gigaset only)
+
      Set the break characters on an M105's internal serial adapter to the six
      bytes stored in brkchars[]. Unused bytes should be set to zero.
 
      ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
      Retrieve version information from the driver. version[0] must be set to
      one of:
+
      - GIGVER_DRIVER: retrieve driver version
      - GIGVER_COMPAT: retrieve interface compatibility version
      - GIGVER_FWBASE: retrieve the firmware version of the base
+
      Upon return, version[] is filled with the requested version information.
 
 2.3. CAPI
-     ----
+---------
+
      The devices will show up as CAPI controllers as soon as the
      corresponding driver module is loaded, and can then be used with
      CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
      driver.
 
 2.5. Unimodem mode
-     -------------
+------------------
+
      In this mode the device works like a modem connected to a serial port
-     (the /dev/ttyGU0, ... mentioned above) which understands the commands
-
-         ATZ                 init, reset
-             => OK or ERROR
-         ATD
-         ATDT                dial
-             => OK, CONNECT,
-                BUSY,
-                NO DIAL TONE,
-                NO CARRIER,
-                NO ANSWER
-         <pause>+++<pause>   change to command mode when connected
-         ATH                 hangup
+     (the /dev/ttyGU0, ... mentioned above) which understands the commands::
+
+         ATZ                 init, reset
+             => OK or ERROR
+         ATD
+         ATDT                dial
+             => OK, CONNECT,
+                BUSY,
+                NO DIAL TONE,
+                NO CARRIER,
+                NO ANSWER
+         <pause>+++<pause>   change to command mode when connected
+         ATH                 hangup
 
      You can use some configuration tool of your distribution to configure this
      "modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
      control lines. This means you must use "Stupid Mode" if you are using
      wvdial or you should use the nocrtscts option of pppd.
      You must also assure that the ppp_async module is loaded with the parameter
-     flag_time=0. You can do this e.g. by adding a line like
+     flag_time=0. You can do this e.g. by adding a line like::
+
+        options ppp_async flag_time=0
 
-        options ppp_async flag_time=0
+     to an appropriate module configuration file, like::
 
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf.
+        /etc/modprobe.d/gigaset.conf.
 
      Unimodem mode is needed for making some devices [e.g. SX100] work which
      do not support the regular Gigaset command set. If debug output (see
-     section 3.2.) shows something like this when dialing:
-         CMD Received: ERROR
-         Available Params: 0
-         Connection State: 0, Response: -1
-         gigaset_process_response: resp_code -1 in ConState 0 !
-         Timeout occurred
+     section 3.2.) shows something like this when dialing::
+
+         CMD Received: ERROR
+         Available Params: 0
+         Connection State: 0, Response: -1
+         gigaset_process_response: resp_code -1 in ConState 0 !
+         Timeout occurred
+
      then switching to unimodem mode may help.
 
      If you have installed the command line tool gigacontr, you can enter
-     unimodem mode using
-         gigacontr --mode unimodem
-     You can switch back using
-         gigacontr --mode isdn
+     unimodem mode using::
+
+         gigacontr --mode unimodem
+
+     You can switch back using::
+
+         gigacontr --mode isdn
 
      You can also put the driver directly into Unimodem mode when it's loaded,
      by passing the module parameter startmode=0 to the hardware specific
-     module, e.g.
+     module, e.g.::
+
         modprobe usb_gigaset startmode=0
-     or by adding a line like
+
+     or by adding a line like::
+
         options usb_gigaset startmode=0
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf
+
+     to an appropriate module configuration file, like::
+
+        /etc/modprobe.d/gigaset.conf
 
 2.6. Call-ID (CID) mode
-     ------------------
+-----------------------
+
      Call-IDs are numbers used to tag commands to, and responses from, the
      Gigaset base in order to support the simultaneous handling of multiple
      ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
      During active operation, the driver switches to the necessary mode
      automatically. However, for the reasons above, the mode chosen when
      the device is not in use (idle) can be selected by the user.
+
      - If you want to receive incoming calls, you can use the default
        settings (CID mode).
      - If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
      If you want both of these at once, you are out of luck.
 
      You can also use the tty class parameter "cidmode" of the device to
-     change its CID mode while the driver is loaded, eg.
-        echo 0 > /sys/class/tty/ttyGU0/cidmode
+     change its CID mode while the driver is loaded, eg.::
+
+        echo 0 > /sys/class/tty/ttyGU0/cidmode
 
 2.7. Dialing Numbers
-     ---------------
-     The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
      be a public network number according to the local dialing plan, without
      any dial prefix for getting an outside line.
 
      Internal calls can be made by providing an internal extension number
-     prefixed with "**" (two asterisks) as the called party number. So to dial
-     eg. the first registered DECT handset, give "**11" as the called party
-     number. Dialing "***" (three asterisks) calls all extensions
+     prefixed with ``**`` (two asterisks) as the called party number. So to dial
+     eg. the first registered DECT handset, give ``**11`` as the called party
+     number. Dialing ``***`` (three asterisks) calls all extensions
      simultaneously (global call).
 
      Unimodem mode does not support internal calls.
 
 2.8. Unregistered Wireless Devices (M101/M105)
-     -----------------------------------------
+----------------------------------------------
+
      The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
      the M101 and M105 wireless devices to be used as ISDN devices for ISDN
      connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
      modes. See the gigacontr(8) manpage for details.
 
 3.   Troubleshooting
-     ---------------
+====================
+
 3.1. Solutions to frequently reported problems
-     -----------------------------------------
+----------------------------------------------
+
      Problem:
-        You have a slow provider and isdn4linux gives up dialing too early.
+        You have a slow provider and isdn4linux gives up dialing too early.
      Solution:
-        Load the isdn module using the dialtimeout option. You can do this e.g.
-        by adding a line like
+        Load the isdn module using the dialtimeout option. You can do this e.g.
+        by adding a line like::
 
-           options isdn dialtimeout=15
+           options isdn dialtimeout=15
 
-        to /etc/modprobe.d/gigaset.conf or a similar file.
+        to /etc/modprobe.d/gigaset.conf or a similar file.
 
      Problem:
-        The isdnlog program emits error messages or just doesn't work.
+        The isdnlog program emits error messages or just doesn't work.
      Solution:
-        Isdnlog supports only the HiSax driver. Do not attempt to use it with
+        Isdnlog supports only the HiSax driver. Do not attempt to use it with
         other drivers such as Gigaset.
 
      Problem:
-        You have two or more DECT data adapters (M101/M105) and only the
-        first one you turn on works.
+        You have two or more DECT data adapters (M101/M105) and only the
+        first one you turn on works.
      Solution:
-        Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+        Select Unimodem mode for all DECT data adapters. (see section 2.5.)
 
      Problem:
-        Messages like this:
+        Messages like this::
+
             usb_gigaset 3-2:1.0: Could not initialize the device.
+
         appear in your syslog.
      Solution:
         Check whether your M10x wireless device is correctly registered to the
         Gigaset base. (see section 2.7.)
 
 3.2. Telling the driver to provide more information
-     ----------------------------------------------
+---------------------------------------------------
      Building the driver with the "Gigaset debugging" kernel configuration
      option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
      information useful for debugging.
 
      You can control the amount of debugging information the driver produces by
-     writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
-        echo 0 > /sys/module/gigaset/parameters/debug
+     writing an appropriate value to /sys/module/gigaset/parameters/debug,
+     e.g.::
+
+        echo 0 > /sys/module/gigaset/parameters/debug
+
      switches off debugging output completely,
-        echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+     ::
+
+        echo 0x302020 > /sys/module/gigaset/parameters/debug
+
      enables a reasonable set of debugging output messages. These values are
      bit patterns where every bit controls a certain type of debugging output.
      See the constants DEBUG_* in the source file gigaset.h for details.
 
      The initial value can be set using the debug parameter when loading the
-     module "gigaset", e.g. by adding a line
-        options gigaset debug=0
+     module "gigaset", e.g. by adding a line::
+
+        options gigaset debug=0
+
      to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
 
      Generated debugging information can be found
-     - as output of the command
-         dmesg
+     - as output of the command::
+
+         dmesg
+
      - in system log files written by your syslog daemon, usually
        in /var/log/, e.g. /var/log/messages.
 
 3.3. Reporting problems and bugs
-     ---------------------------
+--------------------------------
      If you can't solve problems with the driver on your own, feel free to
      use one of the forums, bug trackers, or mailing lists on
-         https://sourceforge.net/projects/gigaset307x
+
+         https://sourceforge.net/projects/gigaset307x
+
      or write an electronic mail to the maintainers.
 
      Try to provide as much information as possible, such as
+
      - distribution
      - kernel version (uname -r)
      - gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
      appropriate forums and newsgroups.
 
 3.4. Reporting problem solutions
-     ---------------------------
+--------------------------------
      If you solved a problem with our drivers, wrote startup scripts for your
      distribution, ... feel free to contact us (using one of the places
      mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
 
 
 4.   Links, other software
-     ---------------------
+==========================
+
      - Sourceforge project developing this driver and associated tools
-         https://sourceforge.net/projects/gigaset307x
+         https://sourceforge.net/projects/gigaset307x
      - Yahoo! Group on the Siemens Gigaset family of devices
-         https://de.groups.yahoo.com/group/Siemens-Gigaset
+         https://de.groups.yahoo.com/group/Siemens-Gigaset
      - Siemens Gigaset/T-Sinus compatibility table
-         http://www.erbze.info/sinus_gigaset.htm
+         http://www.erbze.info/sinus_gigaset.htm
             (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
 
 
 5.   Credits
-     -------
+============
+
      Thanks to
 
      Karsten Keil
-        for his help with isdn4linux
+        for his help with isdn4linux
      Deti Fliegl
-        for his base driver code
+        for his base driver code
      Dennis Dietrich
-        for his kernel 2.6 patches
+        for his kernel 2.6 patches
      Andreas Rummel
-        for his work and logs to get unimodem mode working
+        for his work and logs to get unimodem mode working
      Andreas Degert
-        for his logs and patches to get cx 100 working
+        for his logs and patches to get cx 100 working
      Dietrich Feist
-        for his generous donation of one M105 and two M101 cordless adapters
+        for his generous donation of one M105 and two M101 cordless adapters
      Christoph Schweers
-        for his generous donation of a M34 device
+        for his generous donation of a M34 device
 
      and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
 The hysdn driver has been written by
 Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
 for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-Table of contents
-=================
+.. Table of contents
 
-1. About the driver
+    1. About the driver
 
-2. Loading/Unloading the driver
+    2. Loading/Unloading the driver
 
-3. Entries in the /proc filesystem
+    3. Entries in the /proc filesystem
 
-4. The /proc/net/hysdn/cardconfX file
+    4. The /proc/net/hysdn/cardconfX file
 
-5. The /proc/net/hysdn/cardlogX file
+    5. The /proc/net/hysdn/cardlogX file
 
-6. Where to get additional info and help
+    6. Where to get additional info and help
 
 
 1. About the driver
+===================
 
-   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active 
+   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
    PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
    enable ISDN support in the kernel config and support for HYSDN cards in
-   the active cards submenu. The driver may only be compiled and used if 
+   the active cards submenu. The driver may only be compiled and used if
    support for loadable modules and the process filesystem have been enabled.
 
    These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
    handlers for various protocols like ppp and others as well as config info
    and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
 
-   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 
-   compliant devices with either CAPI 2.0 applications 
+   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+   compliant devices with either CAPI 2.0 applications
    (check isdn4k-utils) or -using the capidrv module- as a regular
-   isdn4linux device. This is done via the same mechanism as with the 
+   isdn4linux device. This is done via the same mechanism as with the
    active AVM cards and in fact uses the same module.
-   
+
 
 2. Loading/Unloading the driver
+===============================
 
    The module has no command line parameters and auto detects up to 10 cards
    in the id-range 0-9.
    If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
-   subdir need to be closed and all ethernet interfaces allocated by this 
+   subdir need to be closed and all ethernet interfaces allocated by this
    driver must be shut down. Otherwise the module counter will avoid a module
    unload.
-   
+
    If you are using the CAPI 2.0-interface, make sure to load/modprobe the
    kernelcapi-module first.
 
@@ -76,52 +80,57 @@ Table of contents
    any avm-specific modules).
 
 3. Entries in the /proc filesystem
+==================================
 
-   When the module has been loaded it adds the directory hysdn in the 
-   /proc/net tree. This directory contains exactly 2 file entries for each 
+   When the module has been loaded it adds the directory hysdn in the
+   /proc/net tree. This directory contains exactly 2 file entries for each
    card. One is called cardconfX and the other cardlogX, where X is the
-   card id number from 0 to 9. 
+   card id number from 0 to 9.
    The cards are numbered in the order found in the PCI config data.
 
 4. The /proc/net/hysdn/cardconfX file
+=====================================
 
-   This file may be read to get by everyone to get info about the cards type, 
+   This file may be read to get by everyone to get info about the cards type,
    actual state, available features and used resources.
    The first 3 entries (id, bus and slot) are PCI info fields, the following
    type field gives the information about the cards type:
 
-   4 -> Ergo card (server card with 2 b-chans)
-   5 -> Metro card (server card with 4 or 8 b-chans)
-   6 -> Champ card (client card with 2 b-chans)   
+   - 4 -> Ergo card (server card with 2 b-chans)
+   - 5 -> Metro card (server card with 4 or 8 b-chans)
+   - 6 -> Champ card (client card with 2 b-chans)
 
    The following 3 fields show the hardware assignments for irq, iobase and the
    dual ported memory (dp-mem).
+
    The fields b-chans and fax-chans announce the available card resources of
    this types for the user.
+
    The state variable indicates the actual drivers state for this card with the
    following assignments.
 
-   0 -> card has not been booted since driver load
-   1 -> card booting is actually in progess
-   2 -> card is in an error state due to a previous boot failure
-   3 -> card is booted and active
+   - 0 -> card has not been booted since driver load
+   - 1 -> card booting is actually in progess
+   - 2 -> card is in an error state due to a previous boot failure
+   - 3 -> card is booted and active
 
    And the last field (device) shows the name of the ethernet device assigned
    to this card. Up to the first successful boot this field only shows a -
    to tell that no net device has been allocated up to now. Once a net device
    has been allocated it remains assigned to this card, even if a card is
-   rebooted and an boot error occurs. 
+   rebooted and an boot error occurs.
 
-   Writing to the cardconfX file boots the card or transfers config lines to 
-   the cards firmware. The type of data is automatically detected when the 
+   Writing to the cardconfX file boots the card or transfers config lines to
+   the cards firmware. The type of data is automatically detected when the
    first data is written. Only root has write access to this file.
    The firmware boot files are normally called hyclient.pof for client cards
    and hyserver.pof for server cards.
    After successfully writing the boot file, complete config files or single
    config lines may be copied to this file.
-   If an error occurs the return value given to the writing process has the 
+   If an error occurs the return value given to the writing process has the
    following additional codes (decimal):
 
+   ==== ============================================
    1000 Another process is currently bootng the card
    1001 Invalid firmware header
    1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
    1006 Second boot stage failure
    1007 Timeout waiting for card ready during boot
    1008 Operation only allowed in booted state
-   1009 Config line too long 
-   1010 Invalid channel number 
+   1009 Config line too long
+   1010 Invalid channel number
    1011 Timeout sending config data
+   ==== ============================================
 
-   Additional info about error reasons may be fetched from the log output. 
+   Additional info about error reasons may be fetched from the log output.
 
 5. The /proc/net/hysdn/cardlogX file
-          
-   The cardlogX file entry may be opened multiple for reading by everyone to 
+====================================
+
+   The cardlogX file entry may be opened multiple for reading by everyone to
    get the cards and drivers log data. Card messages always start with the
-   keyword LOG. All other lines are output from the driver. 
-   The driver log data may be redirected to the syslog by selecting the 
+   keyword LOG. All other lines are output from the driver.
+   The driver log data may be redirected to the syslog by selecting the
    appropriate bitmask. The cards log messages will always be send to this
    interface but never to the syslog.
 
    A root user may write a decimal or hex (with 0x) value t this file to select
-   desired output options. As mentioned above the cards log dat is always 
+   desired output options. As mentioned above the cards log dat is always
    written to the cardlog file independent of the following options only used
    to check and debug the driver itself:
 
-   For example: 
-   echo "0x34560078" > /proc/net/hysdn/cardlog0
+   For example::
+
+        echo "0x34560078" > /proc/net/hysdn/cardlog0
+
    to output the hex log mask 34560078 for card 0.
- 
-   The written value is regarded as an unsigned 32-Bit value, bit ored for 
+
+   The written value is regarded as an unsigned 32-Bit value, bit ored for
    desired output. The following bits are already assigned:
 
-   0x80000000   All driver log data is alternatively via syslog 
+   ==========   ============================================================
+   0x80000000   All driver log data is alternatively via syslog
    0x00000001   Log memory allocation errors
    0x00000010   Firmware load start and close are logged
    0x00000020   Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
    0x00100000   Log all open and close actions to /proc/net/hysdn/card files
    0x00200000   Log all actions from /proc file entries
    0x00010000   Log network interface init and deinit
-   
+   ==========   ============================================================
+
 6. Where to get additional info and help
+========================================
 
-   If you have any problems concerning the driver or configuration contact 
+   If you have any problems concerning the driver or configuration contact
    the Hypercope support team (support@hypercope.de) and or the authors
    Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
    Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   interface_capi
+
+   avmb1
+   gigaset
+   hysdn
+   m_isdn
+
+   credits
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
 Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
 
 1. Overview
+===========
 
 From the CAPI 2.0 specification:
 COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
 
 
 2. Driver and Device Registration
+=================================
 
 CAPI drivers optionally register themselves with Kernel CAPI by calling the
 Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
 
 
 3. Application Registration and Communication
+=============================================
 
 Kernel CAPI forwards registration requests from applications (calls to CAPI
 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
 
 
 4. Data Structures
+==================
 
 4.1 struct capi_driver
+----------------------
 
 This structure describes a Kernel CAPI driver itself. It is used in the
 register_capi_driver() and unregister_capi_driver() functions, and contains
 the following non-private fields, all to be set by the driver before calling
 register_capi_driver():
 
-char name[32]
+``char name[32]``
         the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
         the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
         a callback function pointer (may be NULL)
 
 
 4.2 struct capi_ctr
+-------------------
 
 This structure describes an ISDN device (controller) handled by a Kernel CAPI
 driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
 
 It contains the following non-private fields:
 
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-struct module *owner
+``struct module *owner``
         pointer to the driver module owning the device
 
-void *driverdata
+``void *driverdata``
         an opaque pointer to driver specific data, not touched by Kernel CAPI
 
-char name[32]
+``char name[32]``
         the name of the controller, as a zero-terminated ASCII string
 
-char *driver_name
+``char *driver_name``
         the name of the driver, as a zero-terminated ASCII string
 
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
         (optional) pointer to a callback function for sending firmware and
         configuration data to the device
+
         The function may return before the operation has completed.
+
         Completion must be signalled by a call to capi_ctr_ready().
+
         Return value: 0 on success, error code on error
         Called in process context.
 
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
         (optional) pointer to a callback function for stopping the device,
         releasing all registered applications
+
         The function may return before the operation has completed.
+
         Completion must be signalled by a call to capi_ctr_down().
+
         Called in process context.
 
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
-                        capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
-        pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+        pointers to callback function for registration of
         applications with the device
+
         Calls to these functions are serialized by Kernel CAPI so that only
         one call to any of them is active at any time.
 
-u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+        pointers to callback functions deregistration of
+        applications with the device
+
+        Calls to these functions are serialized by Kernel CAPI so that only
+        one call to any of them is active at any time.
+
+``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
         pointer to a callback function for sending a CAPI message to the
         device
+
         Return value: CAPI error code
+
         If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
         of the skb and the caller may no longer access it. If it returns a
         non-zero (error) value then ownership of the skb returns to the caller
         who may reuse or free it.
+
         The return value should only be used to signal problems with respect
         to accepting or queueing the message. Errors occurring during the
         actual processing of the message should be signaled with an
         appropriate reply message.
+
         May be called in process or interrupt context.
+
         Calls to this function are not serialized by Kernel CAPI, ie. it must
         be prepared to be re-entered.
 
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
         pointer to a callback function returning the entry for the device in
         the CAPI controller info table, /proc/capi/controller
 
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
         pointers to callback functions for the device's proc file
         system entry, /proc/capi/controllers/<n>; pointer to the device's
         capi_ctr structure is available from struct proc_dir_entry::data
         which is available from struct inode.
 
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+  Callback functions except send_message() are never called in interrupt
+  context.
 
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
         value to return for CAPI_GET_MANUFACTURER
 
-capi_version version
+``capi_version version``
         value to return for CAPI_GET_VERSION
 
-capi_profile profile
+``capi_profile profile``
         value to return for CAPI_GET_PROFILE
 
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
         value to return for CAPI_GET_SERIAL
 
 
 4.3 SKBs
+--------
 
 CAPI messages are passed between Kernel CAPI and the driver via send_message()
 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
 
 
 4.4 The _cmsg Structure
+-----------------------
 
 (declared in <linux/isdn/capiutil.h>)
 
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 types are:
 
+=========== =================================================================
 u8          for CAPI parameters of type 'byte'
 
 u16         for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct   alternative representation for CAPI parameters of type 'struct'
             CAPI_COMPOSE: The parameter is present.
             Subparameter values are stored individually in the corresponding
             _cmsg structure members.
+=========== =================================================================
 
 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
 
 
 5. Lower Layer Interface Functions
+==================================
 
 (declared in <linux/isdn/capilli.h>)
 
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
-        register/unregister a driver with Kernel CAPI
+::
+
+  void register_capi_driver(struct capi_driver *drvr)
+  void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+  int attach_capi_ctr(struct capi_ctr *ctrlr)
+  int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
 
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
-        register/unregister a device (controller) with Kernel CAPI
+::
 
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
-        signal controller ready/not ready
+  void capi_ctr_ready(struct capi_ctr *ctrlr)
+  void capi_ctr_down(struct capi_ctr *ctrlr)
 
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
-        signal suspend/resume
+signal controller ready/not ready
 
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
-                                struct sk_buff *skb)
-        pass a received CAPI message to Kernel CAPI
-        for forwarding to the specified application
+::
+
+  void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+  void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+  void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+                               struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
 
 
 6. Helper Functions and Macros
+==============================
 
 Library functions (from <linux/isdn/capilli.h>):
 
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+  void capilib_new_ncci(struct list_head *head, u16 applid,
                         u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+  void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+  void capilib_release_appl(struct list_head *head, u16 applid)
+  void capilib_release(struct list_head *head)
+  void capilib_data_b3_conf(struct list_head *head, u16 applid,
                         u32 ncci, u16 msgid)
-u16  capilib_data_b3_req(struct list_head *head, u16 applid,
+  u16  capilib_data_b3_req(struct list_head *head, u16 applid,
                         u32 ncci, u16 msgid)
 
 
 Macros to extract/set element values from/in a CAPI message header
 (from <linux/isdn/capiutil.h>):
 
+======================  =============================   ====================
 Get Macro               Set Macro                       Element (Type)
-
+======================  =============================   ====================
 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m)	CAPIMSG_SETMSGID(m, msgid)	Message Number (u16)
 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
                                                         (u32)
 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
+======================  =============================   ====================
 
 
 Library functions for working with _cmsg structures
 (from <linux/isdn/capiutil.h>):
 
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
-        Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
-        result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+        Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+        storing the result in ``*msg``.
 
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
-        Disassembles the CAPI 2.0 message in *msg, storing the parameters in
-        *cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+        Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+        in ``*cmsg``.
 
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
-                          u16 Messagenumber, u32 Controller)
-        Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+        Fills the header part and address field of the _cmsg structure ``*cmsg``
         with the given values, zeroing the remainder of the structure so only
         parameters with non-default values need to be changed before sending
         the message.
 
-void capi_cmsg_answer(_cmsg *cmsg)
-        Sets the low bit of the Subcommand field in *cmsg, thereby converting
-        _REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+        Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+        converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
 
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
         Returns the CAPI 2.0 message name corresponding to the given command
         and subcommand values, as a static ASCII string. The return value may
         be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
 
 
 7. Debugging
+============
 
 The module kernelcapi has a module parameter showcapimsgs controlling some
 debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
 mISDN is a new modular ISDN driver, in the long term it should replace
 the old I4L driver architecture for passiv ISDN cards.
 It was designed to allow a broad range of applications and interfaces
 but only have the basic function in kernel, the interface to the user
 space is based on sockets with a own address family AF_ISDN.
-
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index e323a3f2cc81..0f144fad99a6 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -18,6 +18,7 @@ Kernel Build System
     headers_install
 
     issues
+    reproducible-builds
 
 .. only::  subproject and html
 
diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst
new file mode 100644
index 000000000000..ab92e98c89c8
--- /dev/null
+++ b/Documentation/kbuild/reproducible-builds.rst
@@ -0,0 +1,122 @@
+===================
+Reproducible builds
+===================
+
+It is generally desirable that building the same source code with
+the same set of tools is reproducible, i.e. the output is always
+exactly the same.  This makes it possible to verify that the build
+infrastructure for a binary distribution or embedded system has not
+been subverted.  This can also make it easier to verify that a source
+or tool change does not make any difference to the resulting binaries.
+
+The `Reproducible Builds project`_ has more information about this
+general topic.  This document covers the various reasons why building
+the kernel may be unreproducible, and how to avoid them.
+
+Timestamps
+----------
+
+The kernel embeds a timestamp in two places:
+
+* The version string exposed by ``uname()`` and included in
+  ``/proc/version``
+
+* File timestamps in the embedded initramfs
+
+By default the timestamp is the current time.  This must be overridden
+using the `KBUILD_BUILD_TIMESTAMP`_ variable.  If you are building
+from a git commit, you could use its commit date.
+
+The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
+and enables warnings if they are used.  If you incorporate external
+code that does use these, you must override the timestamp they
+correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
+variable.
+
+User, host
+----------
+
+The kernel embeds the building user and host names in
+``/proc/version``.  These must be overridden using the
+`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables.  If you are
+building from a git commit, you could use its committer address.
+
+Absolute filenames
+------------------
+
+When the kernel is built out-of-tree, debug information may include
+absolute filenames for the source files.  This must be overridden by
+including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
+
+Depending on the compiler used, the ``__FILE__`` macro may also expand
+to an absolute filename in an out-of-tree build.  Kbuild automatically
+uses the ``-fmacro-prefix-map`` option to prevent this, if it is
+supported.
+
+The Reproducible Builds web site has more information about these
+`prefix-map options`_.
+
+Generated files in source packages
+----------------------------------
+
+The build processes for some programs under the ``tools/``
+subdirectory do not completely support out-of-tree builds.  This may
+cause a later source package build using e.g. ``make rpm-pkg`` to
+include generated files.  You should ensure the source tree is
+pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
+building a source package.
+
+Module signing
+--------------
+
+If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
+generate a different temporary key for each build, resulting in the
+modules being unreproducible.  However, including a signing key with
+your source would presumably defeat the purpose of signing modules.
+
+One approach to this is to divide up the build process so that the
+unreproducible parts can be treated as sources:
+
+1. Generate a persistent signing key.  Add the certificate for the key
+   to the kernel source.
+
+2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
+   signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
+   empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
+   Build the kernel and modules.
+
+3. Create detached signatures for the modules, and publish them as
+   sources.
+
+4. Perform a second build that attaches the module signatures.  It
+   can either rebuild the modules or use the output of step 2.
+
+Structure randomisation
+-----------------------
+
+If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to
+pre-generate the random seed in
+``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value
+is used in rebuilds.
+
+Debug info conflicts
+--------------------
+
+This is not a problem of unreproducibility, but of generated files
+being *too* reproducible.
+
+Once you set all the necessary variables for a reproducible build, a
+vDSO's debug information may be identical even for different kernel
+versions.  This can result in file conflicts between debug information
+packages for the different kernel versions.
+
+To avoid this, you can make the vDSO different for different
+kernel versions by including an arbitrary string of "salt" in it.
+This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
+
+.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
+.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
+.. _KCFLAGS: kbuild.html#kcflags
+.. _prefix-map options: https://reproducible-builds.org/docs/build-path/
+.. _Reproducible Builds project: https://reproducible-builds.org/
+.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst
index e93ec6645238..66e3792f8a36 100644
--- a/Documentation/locking/spinlocks.rst
+++ b/Documentation/locking/spinlocks.rst
@@ -139,18 +139,6 @@ on other CPU's, because an interrupt on another CPU doesn't interrupt the
 CPU that holds the lock, so the lock-holder can continue and eventually
 releases the lock).
 
-Note that you can be clever with read-write locks and interrupts. For
-example, if you know that the interrupt only ever gets a read-lock, then
-you can use a non-irq version of read locks everywhere - because they
-don't block on each other (and thus there is no dead-lock wrt interrupts.
-But when you do the write-lock, you have to use the irq-safe version.
-
-For an example of being clever with rw-locks, see the "waitqueue_lock"
-handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from
-within an interrupt, they only read the queue in order to know whom to
-wake up. So read-locks are safe (which is good: they are very common
-indeed), while write-locks need to protect themselves against interrupts.
-
                 Linus
 
 ----
diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst
index 3ea9827ba3c7..20e401413991 100644
--- a/Documentation/m68k/README.buddha
+++ b/Documentation/m68k/buddha-driver.rst
@@ -1,3 +1,6 @@
+=====================================
+Amiga Buddha and Catweasel IDE Driver
+=====================================
 
 The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
 Geert Uytterhoeven based on the following specifications:
@@ -12,12 +15,12 @@ described  in  their  manuals, no tricks have been used (for
 example leaving some address lines out of the equations...).
 If you want to configure the board yourself (for example let
 a  Linux  kernel  configure the card), look at the Commodore
-Docs.  Reading the nibbles should give this information:
+Docs.  Reading the nibbles should give this information::
 
-Vendor number: 4626 ($1212)
-product number: 0 (42 for Catweasel Z-II)
-Serial number: 0
-Rom-vector: $1000
+  Vendor number: 4626 ($1212)
+  product number: 0 (42 for Catweasel Z-II)
+  Serial number: 0
+  Rom-vector: $1000
 
 The  card  should be a Z-II board, size 64K, not for freemem
 list, Rom-Vektor is valid, no second Autoconfig-board on the
@@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-).
 
 The local memory-map is even active when mapped to $e8:
 
+==============  ===========================================
 $0-$7e          Autokonfig-space, see Z-II docs.
 
 $80-$7fd        reserved
@@ -50,50 +54,51 @@ $a00-$aff	IDE-Select 2 (Port 1, Register set 0)
 $b00-$bff       IDE-Select 3 (Port 1, Register set 1)
 
 $c00-$cff       IDE-Select 4 (Port 2, Register set 0,
-                          Catweasel only!)
+                Catweasel only!)
 
 $d00-$dff       IDE-Select 5 (Port 3, Register set 1,
-                              Catweasel only!)
+                Catweasel only!)
 
-$e00-$eff       local expansion port, on Catweasel Z-II the 
+$e00-$eff       local expansion port, on Catweasel Z-II the
                 Catweasel registers are also mapped here.
                 Never touch, use multidisk.device!
-                
-$f00            read only, Byte-access: Bit 7 shows the 
-                level of the IRQ-line of IDE port 0. 
+
+$f00            read only, Byte-access: Bit 7 shows the
+                level of the IRQ-line of IDE port 0.
 
 $f01-$f3f       mirror of $f00
 
-$f40            read only, Byte-access: Bit 7 shows the 
-                level of the IRQ-line of IDE port 1. 
+$f40            read only, Byte-access: Bit 7 shows the
+                level of the IRQ-line of IDE port 1.
 
 $f41-$f7f       mirror of $f40
 
-$f80            read only, Byte-access: Bit 7 shows the 
-                level of the IRQ-line of IDE port 2. 
+$f80            read only, Byte-access: Bit 7 shows the
+                level of the IRQ-line of IDE port 2.
                 (Catweasel only!)
 
 $f81-$fbf       mirror of $f80
 
 $fc0            write-only: Writing any value to this
-                register enables IRQs to be passed from the 
-                IDE ports to the Zorro bus. This mechanism 
-                has been implemented to be compatible with 
+                register enables IRQs to be passed from the
+                IDE ports to the Zorro bus. This mechanism
+                has been implemented to be compatible with
                 harddisks that are either defective or have
-                a buggy firmware and pull the IRQ line up 
-                while starting up. If interrupts would 
-                always be passed to the bus, the computer 
-                might not start up. Once enabled, this flag 
-                can not be disabled again. The level of the 
-                flag can not be determined by software 
+                a buggy firmware and pull the IRQ line up
+                while starting up. If interrupts would
+                always be passed to the bus, the computer
+                might not start up. Once enabled, this flag
+                can not be disabled again. The level of the
+                flag can not be determined by software
                 (what for? Write to me if it's necessary!).
 
 $fc1-$fff       mirror of $fc0
 
 $1000-$ffff     Buddha-Rom with offset $1000 in the rom
-                chip. The addresses $0 to $fff of the rom 
+                chip. The addresses $0 to $fff of the rom
                 chip cannot be read. Rom is Byte-wide and
                 mapped to even addresses.
+==============  ===========================================
 
 The  IDE ports issue an INT2.  You can read the level of the
 IRQ-lines  of  the  IDE-ports by reading from the three (two
@@ -128,7 +133,8 @@ must  always  be set to 1 to be compatible with later Buddha
 versions  (if  I'll  ever  update this one).  I presume that
 I'll  never use the lower four bits, but they have to be set
 to 1 by definition.
-  The  values in this table have to be shifted 5 bits to the
+
+The  values in this table have to be shifted 5 bits to the
 left and or'd with $1f (this sets the lower 5 bits).
 
 All  the timings have in common:  Select and IOR/IOW rise at
@@ -138,44 +144,36 @@ values  are no multiple of 71.  One clock-cycle is 71ns long
 (exactly 70,5 at 14,18 Mhz on PAL systems).
 
 value 0 (Default after reset)
-
-497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
-(same timing as the Amiga 1200 does on it's IDE port without
-accelerator card)
+  497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
+  (same timing as the Amiga 1200 does on it's IDE port without
+  accelerator card)
 
 value 1
-
-639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+  639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
 
 value 2
-
-781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+  781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
 
 value 3
-
-355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+  355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
 
 value 4
-
-355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
+  355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
 
 value 5
-
-355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+  355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
 
 value 6
-
-1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+  1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
 
 value 7
-
-355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+  355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
 
 When accessing IDE registers with A6=1 (for example $84x),
 the timing will always be mode 0 8-bit compatible, no matter
 what you have selected in the speed register:
 
-781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. 
+781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
 
 All  the  timings with a very short select-signal (the 355ns
 fast  accesses)  depend  on the accelerator card used in the
@@ -204,7 +202,8 @@ always  shows a "no IRQ here" on the Buddha, and accesses to
 the  third  IDE  port  are  going into data's Nirwana on the
 Buddha.
 
-                            Jens Schönfeld february 19th, 1997
-                                        updated may 27th, 1997
-                             eMail: sysop@nostlgic.tng.oche.de
+Jens Schönfeld february 19th, 1997
+
+updated may 27th, 1997
 
+eMail: sysop@nostlgic.tng.oche.de
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index 3a5ba7fe1703..b89cb6a86d9b 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -8,6 +8,7 @@ m68k Architecture
    :maxdepth: 2
 
    kernel-options
+   buddha-driver
 
 .. only::  subproject and html
 
diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst
index 22b271de0304..1a2f99b67d25 100644
--- a/Documentation/maintainer/pull-requests.rst
+++ b/Documentation/maintainer/pull-requests.rst
@@ -29,7 +29,7 @@ request to.
 In order to create the pull request you must first tag the branch that you
 have just created. It is recommended that you choose a meaningful tag name,
 in a way that you and others can understand, even after some time.  A good
-practice is to include in the name an indicator of the sybsystem of origin
+practice is to include in the name an indicator of the subsystem of origin
 and the target kernel version.
 
 Greg offers the following. A pull request with miscellaneous stuff for
diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst
index ff675a1b1422..2f9c2cff6738 100644
--- a/Documentation/mips/AU1xxx_IDE.README
+++ b/Documentation/mips/au1xxx_ide.rst
@@ -1,7 +1,14 @@
-README for MIPS AU1XXX IDE driver - Released 2005-07-15
+.. include:: <isonum.txt>
+
+======================
+MIPS AU1XXX IDE driver
+======================
+
+Released 2005-07-15
+
+About
+=====
 
-ABOUT
------
 This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
 services they provide.
 
@@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
 section.
 
 
-LICENSE
--------
+License
+=======
 
-Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions
+:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions
 
 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
 version.
 
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
@@ -35,31 +42,35 @@ You should have received a copy of the GNU General Public License along with
 this program; if not, write to the Free Software Foundation, Inc.,
 675 Mass Ave, Cambridge, MA 02139, USA.
 
-Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
+Note:
+      for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
       Interface and Linux Device Driver" Application Note.
 
 
-FILES, CONFIGS AND COMPATIBILITY
---------------------------------
+Files, Configs and Compatibility
+================================
 
 Two files are introduced:
 
   a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
      contains : struct _auide_hwif
-                 timing parameters for PIO mode 0/1/2/3/4
-                 timing parameters for MWDMA 0/1/2
+
+                - timing parameters for PIO mode 0/1/2/3/4
+                - timing parameters for MWDMA 0/1/2
 
   b) 'drivers/ide/mips/au1xxx-ide.c'
      contains the functionality of the AU1XXX IDE driver
 
 Following extra configs variables are introduced:
 
-  CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA    - enable the PIO+DBDMA mode
-  CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA  - enable the MWDMA mode
+  CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA
+        - enable the PIO+DBDMA mode
+  CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA
+        - enable the MWDMA mode
 
 
-SUPPORTED IDE MODES
--------------------
+Supported IDE Modes
+===================
 
 The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
 MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
@@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g.
 -X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
 
 
-PERFORMANCE CONFIGURATIONS
---------------------------
+Performance Configurations
+==========================
 
-If the used system doesn't need USB support enable the following kernel configs:
+If the used system doesn't need USB support enable the following kernel
+configs::
 
-CONFIG_IDE=y
-CONFIG_BLK_DEV_IDE=y
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+    CONFIG_IDE=y
+    CONFIG_BLK_DEV_IDE=y
+    CONFIG_IDE_GENERIC=y
+    CONFIG_BLK_DEV_IDEPCI=y
+    CONFIG_BLK_DEV_GENERIC=y
+    CONFIG_BLK_DEV_IDEDMA_PCI=y
+    CONFIG_BLK_DEV_IDE_AU1XXX=y
+    CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+    CONFIG_BLK_DEV_IDEDMA=y
 
 Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
 the burst support on DBDMA controller.
@@ -90,20 +102,22 @@ the burst support on DBDMA controller.
 If the used system need the USB support enable the following kernel configs for
 high IDE to USB throughput.
 
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+::
+
+    CONFIG_IDE_GENERIC=y
+    CONFIG_BLK_DEV_IDEPCI=y
+    CONFIG_BLK_DEV_GENERIC=y
+    CONFIG_BLK_DEV_IDEDMA_PCI=y
+    CONFIG_BLK_DEV_IDE_AU1XXX=y
+    CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+    CONFIG_BLK_DEV_IDEDMA=y
 
 Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
 disable the burst support on DBDMA controller.
 
 
-ACKNOWLEDGMENTS
----------------
+Acknowledgments
+===============
 
 These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
 IDE driver from AMD.
@@ -112,4 +126,5 @@ Additional input also from:
 Matthias Lenk <matthias.lenk@amd.com>
 
 Happy hacking!
+
 Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
new file mode 100644
index 000000000000..fd9023c8a89f
--- /dev/null
+++ b/Documentation/mips/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+MIPS architecture
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   au1xxx_ide
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst
index 757ccfaa1385..07afc8063d4d 100644
--- a/Documentation/networking/caif/README
+++ b/Documentation/networking/caif/caif.rst
@@ -1,18 +1,31 @@
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
+:orphan:
 
-=== Start ===
-If you have compiled CAIF for modules do:
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
 
+================
+Using Linux CAIF
+================
 
-=== Preparing the setup with a STE modem ===
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+    $modprobe crc_ccitt
+    $modprobe caif
+    $modprobe caif_socket
+    $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
 
 If you are working on integration of CAIF you should make sure
 that the kernel is built with module support.
@@ -32,24 +45,30 @@ module parameter "ser_use_stx".
 Normally Frame Checksum is always used on UART, but this is also provided as a
 module parameter "ser_use_fcs".
 
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
+::
+
+    $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+    $ ifconfig caif_ttyS0 up
 
-PLEASE NOTE:    There is a limitation in Android shell.
+PLEASE NOTE:
+                There is a limitation in Android shell.
                 It only accepts one argument to insmod/modprobe!
 
-=== Trouble shooting ===
+Trouble shooting
+================
 
 There are debugfs parameters provided for serial communication.
 /sys/kernel/debug/caif_serial/<tty-name>/
 
 * ser_state:   Prints the bit-mask status where
+
   - 0x02 means SENDING, this is a transient state.
   - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
-        and is blocking further send operation. Flow OFF has been propagated
-        to all CAIF Channels using this TTY.
+    and is blocking further send operation. Flow OFF has been propagated
+    to all CAIF Channels using this TTY.
 
 * tty_status: Prints the bit-mask tty status information
+
   - 0x01 - tty->warned is on.
   - 0x02 - tty->low_latency is on.
   - 0x04 - tty->packed is on.
@@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication.
   - 0x20 - tty->stopped is on.
 
 * last_tx_msg: Binary blob Prints the last transmitted frame.
-        This can be printed with
+
+  This can be printed with::
+
         $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
-        The first two tx messages sent look like this. Note: The initial
-        byte 02 is start of frame extension (STX) used for re-syncing
-        upon errors.
 
-  - Enumeration:
+  The first two tx messages sent look like this. Note: The initial
+  byte 02 is start of frame extension (STX) used for re-syncing
+  upon errors.
+
+  - Enumeration::
+
         0000000  02 05 00 00 03 01 d2 02
                  |  |     |  |  |  |
                  STX(1)   |  |  |  |
@@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication.
                              Command:Enumeration(1)
                                 Link-ID(1)
                                     Checksum(2)
-  - Channel Setup:
+
+  - Channel Setup::
+
         0000000  02 07 00 00 00 21 a1 00 48 df
                  |  |     |  |  |  |  |  |
                  STX(1)   |  |  |  |  |  |
@@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication.
                                           Checksum(2)
 
 * last_rx_msg: Prints the last transmitted frame.
-        The RX messages for LinkSetup look almost identical but they have the
-        bit 0x20 set in the command bit, and Channel Setup has added one byte
-        before Checksum containing Channel ID.
-        NOTE: Several CAIF Messages might be concatenated. The maximum debug
+
+  The RX messages for LinkSetup look almost identical but they have the
+  bit 0x20 set in the command bit, and Channel Setup has added one byte
+  before Checksum containing Channel ID.
+
+  NOTE:
+        Several CAIF Messages might be concatenated. The maximum debug
         buffer size is 128 bytes.
 
-== Error Scenarios:
+Error Scenarios
+===============
+
 - last_tx_msg contains channel setup message and last_rx_msg is empty ->
   The host seems to be able to send over the UART, at least the CAIF ldisc get
   notified that sending is completed.
@@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication.
 
 - if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
   might be problems transmitting over UART.
+
   E.g. host and modem wiring is not correct you will typically see
   tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
   You will probably see the enumeration message in last_tx_message
   and empty last_rx_message.
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
    google/gve
    mellanox/mlx5
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
    tls
    tls-offload
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
index 3566a725d19c..d2266ce5534e 100644
--- a/Documentation/networking/mac80211_hwsim/README
+++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
@@ -1,5 +1,13 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
 mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as
@@ -7,6 +15,7 @@ published by the Free Software Foundation.
 
 
 Introduction
+============
 
 mac80211_hwsim is a Linux kernel module that can be used to simulate
 arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
@@ -43,6 +52,7 @@ regardless of channel.
 
 
 Simple example
+==============
 
 This example shows how to use mac80211_hwsim to simulate two radios:
 one to act as an access point and the other as a station that
@@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take
 care of WPA2-PSK authentication. In addition, hostapd is also
 processing access point side of association.
 
+::
+
 
-# Build mac80211_hwsim as part of kernel configuration
+    # Build mac80211_hwsim as part of kernel configuration
 
-# Load the module
-modprobe mac80211_hwsim
+    # Load the module
+    modprobe mac80211_hwsim
 
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
+    # Run hostapd (AP) for wlan0
+    hostapd hostapd.conf
 
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+    # Run wpa_supplicant (station) for wlan1
+    wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
 
 
 More test cases are available in hostap.git:
diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst
index 054a67d55563..43da3f7cee76 100644
--- a/Documentation/nios2/README
+++ b/Documentation/nios2/nios2.rst
@@ -1,3 +1,4 @@
+=================================
 Linux on the Nios II architecture
 =================================
 
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   openrisc_port
+   todo
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
 OpenRISC Linux
 ==============
 
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
 
 For information about OpenRISC processors and ongoing development:
 
+        =======         =============================
         website         http://openrisc.io
         email           openrisc@lists.librecores.org
+        =======         =============================
 
 ---------------------------------------------------------------------
 
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
 Instructions for building the different toolchains can be found on openrisc.io
 or Stafford's toolchain build and release scripts.
 
+        ==========      =================================================
         binaries        https://github.com/openrisc/or1k-gcc/releases
         toolchains      https://openrisc.io/software
         building        https://github.com/stffrdhrn/or1k-toolchain-build
+        ==========      =================================================
 
 2) Building
 
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
 
         make ARCH=openrisc defconfig
         make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC.  During the build FPGA RTL is code
 downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
 tools.  Binaries are loaded onto the board with openocd.
 
+::
+
         git clone https://github.com/olofk/fusesoc
         cd fusesoc
         sudo pip install -e .
@@ -65,7 +72,9 @@ platform.  Please follow the OpenRISC instructions on the QEMU website to get
 Linux running on QEMU.  You can build QEMU yourself, but your Linux distribution
 likely provides binary packages to support OpenRISC.
 
+        =============   ======================================================
         qemu openrisc   https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+        =============   ======================================================
 
 ---------------------------------------------------------------------
 
@@ -75,36 +84,38 @@ Terminology
 In the code, the following particles are used on symbols to limit the scope
 to more or less specific processor implementations:
 
+========= =======================================
 openrisc: the OpenRISC class of processors
 or1k:     the OpenRISC 1000 family of processors
 or1200:   the OpenRISC 1200 processor
+========= =======================================
 
 ---------------------------------------------------------------------
 
 History
 ========
 
-18. 11. 2003    Matjaz Breskvar (phoenix@bsemi.com)
+18-11-2003      Matjaz Breskvar (phoenix@bsemi.com)
         initial port of linux to OpenRISC/or32 architecture.
         all the core stuff is implemented and seams usable.
 
-08. 12. 2003    Matjaz Breskvar (phoenix@bsemi.com)
+08-12-2003      Matjaz Breskvar (phoenix@bsemi.com)
         complete change of TLB miss handling.
         rewrite of exceptions handling.
         fully functional sash-3.6 in default initrd.
         a much improved version with changes all around.
 
-10. 04. 2004    Matjaz Breskvar (phoenix@bsemi.com)
+10-04-2004      Matjaz Breskvar (phoenix@bsemi.com)
         alot of bugfixes all over.
         ethernet support, functional http and telnet servers.
         running many standard linux apps.
 
-26. 06. 2004    Matjaz Breskvar (phoenix@bsemi.com)
+26-06-2004      Matjaz Breskvar (phoenix@bsemi.com)
         port to 2.6.x
 
-30. 11. 2004    Matjaz Breskvar (phoenix@bsemi.com)
+30-11-2004      Matjaz Breskvar (phoenix@bsemi.com)
         lots of bugfixes and enhancments.
         added opencores framebuffer driver.
 
-09. 10. 2010    Jonas Bonn (jonas@southpole.se)
+09-10-2010    Jonas Bonn (jonas@southpole.se)
         major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
 The OpenRISC Linux port is fully functional and has been tracking upstream
 since 2.6.35.  There are, however, remaining items to be completed within
 the coming months.  Here's a list of known-to-be-less-than-stellar items
 that are due for investigation shortly, i.e. our TODO list:
 
--- Implement the rest of the DMA API... dma_map_sg, etc.
+-  Implement the rest of the DMA API... dma_map_sg, etc.
 
--- Finish the renaming cleanup... there are references to or32 in the code
+-  Finish the renaming cleanup... there are references to or32 in the code
    which was an older name for the architecture.  The name we've settled on is
    or1k and this change is slowly trickling through the stack.  For the time
    being, or32 is equivalent to or1k.
-
diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst
index 7d75223fa18d..de1b60402c5b 100644
--- a/Documentation/parisc/debugging
+++ b/Documentation/parisc/debugging.rst
@@ -1,8 +1,13 @@
+=================
+PA-RISC Debugging
+=================
+
 okay, here are some hints for debugging the lower-level parts of
 linux/parisc.
 
 
 1. Absolute addresses
+=====================
 
 A lot of the assembly code currently runs in real mode, which means
 absolute addresses are used instead of virtual addresses as in the
@@ -12,6 +17,7 @@ currently).
 
 
 2. HPMCs
+========
 
 When real-mode code tries to access non-existent memory, you'll get
 an HPMC instead of a kernel oops.  To debug an HPMC, try to find
@@ -27,6 +33,7 @@ access it.
 
 
 3. Q bit fun
+============
 
 Certain, very critical code has to clear the Q bit in the PSW.  What
 happens when the Q bit is cleared is the CPU does not update the
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
new file mode 100644
index 000000000000..aa3ee0470425
--- /dev/null
+++ b/Documentation/parisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+PA-RISC Architecture
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   debugging
+   registers
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst
index 10c7d1730f5d..59c8ecf3e856 100644
--- a/Documentation/parisc/registers
+++ b/Documentation/parisc/registers.rst
@@ -1,11 +1,16 @@
+================================
 Register Usage for Linux/PA-RISC
+================================
 
 [ an asterisk is used for planned usage which is currently unimplemented ]
 
-        General Registers as specified by ABI
+General Registers as specified by ABI
+=====================================
 
-        Control Registers
+Control Registers
+-----------------
 
+=============================== ===============================================
 CR 0 (Recovery Counter)         used for ptrace
 CR 1-CR 7(undefined)            unused
 CR 8 (Protection ID)            per-process value*
@@ -29,26 +34,35 @@ CR28 (TR 4)			not used
 CR29 (TR 5)                     not used
 CR30 (TR 6)                     current / 0
 CR31 (TR 7)                     Temporary register, used in various places
+=============================== ===============================================
 
-        Space Registers (kernel mode)
+Space Registers (kernel mode)
+-----------------------------
 
+=============================== ===============================================
 SR0                             temporary space register
 SR4-SR7                         set to 0
 SR1                             temporary space register
 SR2                             kernel should not clobber this
 SR3                             used for userspace accesses (current process)
+=============================== ===============================================
 
-        Space Registers (user mode)
+Space Registers (user mode)
+---------------------------
 
+=============================== ===============================================
 SR0                             temporary space register
 SR1                             temporary space register
 SR2                             holds space of linux gateway page
 SR3                             holds user address space value while in kernel
 SR4-SR7                         Defines short address space for user/kernel
+=============================== ===============================================
 
 
-        Processor Status Word
+Processor Status Word
+---------------------
 
+=============================== ===============================================
 W (64-bit addresses)            0
 E (Little-endian)               0
 S (Secure Interval Timer)       0
@@ -69,15 +83,19 @@ Q (collect interruption state)	1 (0 in code directly preceding an rfi)
 P (Protection Identifiers)      1*
 D (Data address translation)    1, 0 while executing real-mode code
 I (external interrupt mask)     used by cli()/sti() macros
+=============================== ===============================================
 
-        "Invisible" Registers
+"Invisible" Registers
+---------------------
 
+=============================== ===============================================
 PSW default W value             0
 PSW default E value             0
 Shadow Registers                used by interruption handler code
 TOC enable bit                  1
+=============================== ===============================================
 
-=========================================================================
+-------------------------------------------------------------------------
 
 The PA-RISC architecture defines 7 registers as "shadow registers".
 Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
@@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register
 (GR) saves and restores in interruption handlers.
 Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
 
-=========================================================================
+-------------------------------------------------------------------------
+
 Register usage notes, originally from John Marvin, with some additional
 notes from Randolph Chung.
 
@@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling
 another procedure. Some of the above registers do have special meanings
 that you should be aware of:
 
-    r1: The addil instruction is hardwired to place its result in r1,
+    r1:
+        The addil instruction is hardwired to place its result in r1,
         so if you use that instruction be aware of that.
 
-    r2: This is the return pointer. In general you don't want to
+    r2:
+        This is the return pointer. In general you don't want to
         use this, since you need the pointer to get back to your
         caller. However, it is grouped with this set of registers
         since the caller can't rely on the value being the same
@@ -107,23 +128,27 @@ that you should be aware of:
         and return through that register after trashing r2, and
         that should not cause a problem for the calling routine.
 
-    r19-r22: these are generally regarded as temporary registers.
+    r19-r22:
+        these are generally regarded as temporary registers.
         Note that in 64 bit they are arg7-arg4.
 
-    r23-r26: these are arg3-arg0, i.e. you can use them if you
+    r23-r26:
+        these are arg3-arg0, i.e. you can use them if you
         don't care about the values that were passed in anymore.
 
-    r28,r29: are ret0 and ret1. They are what you pass return values
+    r28,r29:
+        are ret0 and ret1. They are what you pass return values
         in. r28 is the primary return. When returning small structures
         r29 may also be used to pass data back to the caller.
 
-    r30: stack pointer
+    r30:
+        stack pointer
 
-    r31: the ble instruction puts the return pointer in here.
+    r31:
+        the ble instruction puts the return pointer in here.
 
 
-r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
+    r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
     general purpose registers. r27 is the data pointer, and is
     used to make references to global variables easier. r30 is
     the stack pointer.
-
diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
index 07faa5457bcb..5273d06c8ff6 100644
--- a/Documentation/process/email-clients.rst
+++ b/Documentation/process/email-clients.rst
@@ -40,7 +40,7 @@ Emailed patches should be in ASCII or UTF-8 encoding only.
 If you configure your email client to send emails with UTF-8 encoding,
 you avoid some possible charset problems.
 
-Email clients should generate and maintain References: or In-Reply-To:
+Email clients should generate and maintain "References:" or "In-Reply-To:"
 headers so that mail threading is not broken.
 
 Copy-and-paste (or cut-and-paste) usually does not work for patches
@@ -89,7 +89,7 @@ Claws Mail (GUI)
 
 Works. Some people use this successfully for patches.
 
-To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
+To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`)
 or an external editor.
 
 If the inserted patch has to be edited in the Claws composition window
@@ -132,8 +132,8 @@ wrapping.
 At the bottom of your email, put the commonly-used patch delimiter before
 inserting your patch:  three hyphens (``---``).
 
-Then from the :menuselection:`Message` menu item, select insert file and
-choose your patch.
+Then from the :menuselection:`Message` menu item, select
+:menuselection:`insert file` and choose your patch.
 As an added bonus you can customise the message creation toolbar menu
 and put the :menuselection:`insert file` icon there.
 
@@ -149,18 +149,16 @@ patches so do not GPG sign them.  Signing patches that have been inserted
 as inlined text will make them tricky to extract from their 7-bit encoding.
 
 If you absolutely must send patches as attachments instead of inlining
-them as text, right click on the attachment and select properties, and
-highlight :menuselection:`Suggest automatic display` to make the attachment
+them as text, right click on the attachment and select :menuselection:`properties`,
+and highlight :menuselection:`Suggest automatic display` to make the attachment
 inlined to make it more viewable.
 
 When saving patches that are sent as inlined text, select the email that
 contains the patch from the message list pane, right click and select
 :menuselection:`save as`.  You can use the whole email unmodified as a patch
-if it was properly composed.  There is no option currently to save the email
-when you are actually viewing it in its own window -- there has been a request
-filed at kmail's bugzilla and hopefully this will be addressed.  Emails are
-saved as read-write for user only so you will have to chmod them to make them
-group and world readable if you copy them elsewhere.
+if it was properly composed.  Emails are saved as read-write for user only so
+you will have to chmod them to make them group and world readable if you copy
+them elsewhere.
 
 Lotus Notes (GUI)
 *****************
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 6ab75c11d2c3..b6f5a379ad6c 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -123,7 +123,7 @@ required reading:
                 https://www.ozlabs.org/~akpm/stuff/tpp.txt
 
         "Linux kernel patch submission format"
-                http://linux.yyz.us/patch-format.html
+                https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
 
   :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
     This file describes the rationale behind the conscious decision to
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 9c4299293c72..fb56297f70dc 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -844,7 +844,7 @@ Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
 
 Jeff Garzik, "Linux kernel patch submission format".
-  <http://linux.yyz.us/patch-format.html>
+  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
 
 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
   <http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.rst
index 14b1492f689b..7b4d1d747585 100644
--- a/Documentation/riscv/boot-image-header.txt
+++ b/Documentation/riscv/boot-image-header.rst
@@ -1,22 +1,25 @@
-                                Boot image header in RISC-V Linux
-                        =============================================
+=================================
+Boot image header in RISC-V Linux
+=================================
 
-Author: Atish Patra <atish.patra@wdc.com>
-Date  : 20 May 2019
+:Author: Atish Patra <atish.patra@wdc.com>
+:Date:   20 May 2019
 
 This document only describes the boot image header details for RISC-V Linux.
-The complete booting guide will be available at Documentation/riscv/booting.txt.
 
-The following 64-byte header is present in decompressed Linux kernel image.
+TODO:
+  Write a complete booting guide.
+
+The following 64-byte header is present in decompressed Linux kernel image::
 
         u32 code0;                /* Executable code */
-        u32 code1;                /* Executable code */
+        u32 code1;                /* Executable code */
         u64 text_offset;          /* Image load offset, little endian */
         u64 image_size;           /* Effective Image size, little endian */
         u64 flags;                /* kernel flags, little endian */
         u32 version;              /* Version of this header */
-        u32 res1  = 0;            /* Reserved */
-        u64 res2  = 0;            /* Reserved */
+        u32 res1 = 0;             /* Reserved */
+        u64 res2 = 0;             /* Reserved */
         u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
         u32 magic2 = 0x56534905;  /* Magic number 2, little endian, "RSC\x05" */
         u32 res4;                 /* Reserved for PE COFF offset */
@@ -25,16 +28,21 @@ This header format is compliant with PE/COFF header and largely inspired from
 ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
 header in future.
 
-Notes:
+Notes
+=====
+
 - This header can also be reused to support EFI stub for RISC-V in future. EFI
   specification needs PE/COFF image header in the beginning of the kernel image
   in order to load it as an EFI application. In order to support EFI stub,
   code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should
   point to the rest of the PE/COFF header.
 
-- version field indicate header version number.
-        Bits 0:15  - Minor version
-        Bits 16:31 - Major version
+- version field indicate header version number
+
+        ==========  =============
+        Bits 0:15   Minor version
+        Bits 16:31  Major version
+        ==========  =============
 
   This preserves compatibility across newer and older version of the header.
   The current version is defined as 0.2.
@@ -45,7 +53,10 @@ Notes:
   The "magic2" field replaces it, matching up with the ARM64 header.
 
 - In current header, the flags field has only one field.
-        Bit 0: Kernel endianness. 1 if BE, 0 if LE.
+
+        =====  ====================================
+        Bit 0  Kernel endianness. 1 if BE, 0 if LE.
+        =====  ====================================
 
 - Image size is mandatory for boot loader to load kernel image. Booting will
   fail otherwise.
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
index e3ca0922a8c2..215fd3c1f2d5 100644
--- a/Documentation/riscv/index.rst
+++ b/Documentation/riscv/index.rst
@@ -5,6 +5,7 @@ RISC-V architecture
 .. toctree::
     :maxdepth: 1
 
+    boot-image-header
     pmu
 
 .. only::  subproject and html
diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
index 487852fda33e..fc40e9f23c85 100644
--- a/Documentation/security/tpm/index.rst
+++ b/Documentation/security/tpm/index.rst
@@ -4,6 +4,7 @@ Trusted Platform Module documentation
 
 .. toctree::
 
+   tpm_event_log
    tpm_vtpm_proxy
    xen-tpmfront
    tpm_ftpm_tee
diff --git a/Documentation/security/tpm/tpm_event_log.rst b/Documentation/security/tpm/tpm_event_log.rst
new file mode 100644
index 000000000000..f00f7a1d5e92
--- /dev/null
+++ b/Documentation/security/tpm/tpm_event_log.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+TPM Event Log
+=============
+
+This document briefly describes what TPM log is and how it is handed
+over from the preboot firmware to the operating system.
+
+Introduction
+============
+
+The preboot firmware maintains an event log that gets new entries every
+time something gets hashed by it to any of the PCR registers. The events
+are segregated by their type and contain the value of the hashed PCR
+register. Typically, the preboot firmware will hash the components to
+who execution is to be handed over or actions relevant to the boot
+process.
+
+The main application for this is remote attestation and the reason why
+it is useful is nicely put in the very first section of [1]:
+
+"Attestation is used to provide information about the platform’s state
+to a challenger. However, PCR contents are difficult to interpret;
+therefore, attestation is typically more useful when the PCR contents
+are accompanied by a measurement log. While not trusted on their own,
+the measurement log contains a richer set of information than do the PCR
+contents. The PCR contents are used to provide the validation of the
+measurement log."
+
+UEFI event log
+==============
+
+UEFI provided event log has a few somewhat weird quirks.
+
+Before calling ExitBootServices() Linux EFI stub copies the event log to
+a custom configuration table defined by the stub itself. Unfortunately,
+the events generated by ExitBootServices() don't end up in the table.
+
+The firmware provides so called final events configuration table to sort
+out this issue. Events gets mirrored to this table after the first time
+EFI_TCG2_PROTOCOL.GetEventLog() gets called.
+
+This introduces another problem: nothing guarantees that it is not called
+before the Linux EFI stub gets to run. Thus, it needs to calculate and save the
+final events table size while the stub is still running to the custom
+configuration table so that the TPM driver can later on skip these events when
+concatenating two halves of the event log from the custom configuration table
+and the final events table.
+
+References
+==========
+
+- [1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/
+- [2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
    hd-audio/index
    cards/index
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 77e89c1956d7..5b6119ff69f4 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -25,8 +25,9 @@ RE_function = re.compile(r'([\w_][\w\d_]+\(\))')
 # to the creation of incorrect and confusing cross references.  So
 # just don't even try with these names.
 #
-Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap'
-              'select', 'poll', 'fork', 'execve', 'clone', 'ioctl']
+Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
+              'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
+              'socket' ]
 
 #
 # Find all occurrences of function() and try to replace them with
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
 spi_butterfly - parport-to-butterfly adapter driver
 ===================================================
 
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
 connector pins (used also on non-Butterfly AVR boards).  On the parport
 side this is like "sp12" programming cables.
 
+        ======    =============   ===================
         Signal    Butterfly       Parport (DB-25)
-        ------    ---------       ---------------
-        SCK     = J403.PB1/SCK  = pin 2/D0
-        RESET   = J403.nRST     = pin 3/D1
-        VCC     = J403.VCC_EXT  = pin 8/D6
-        MOSI    = J403.PB2/MOSI = pin 9/D7
-        MISO    = J403.PB3/MISO = pin 11/S7,nBUSY
-        GND     = J403.GND      = pin 23/GND
+        ======    =============   ===================
+        SCK       J403.PB1/SCK    pin 2/D0
+        RESET     J403.nRST       pin 3/D1
+        VCC       J403.VCC_EXT    pin 8/D6
+        MOSI      J403.PB2/MOSI   pin 9/D7
+        MISO      J403.PB3/MISO   pin 11/S7,nBUSY
+        GND       J403.GND        pin 23/GND
+        ======    =============   ===================
 
 Then to let Linux master that bus to talk to the DataFlash chip, you must
 (a) flash new firmware that disables SPI (set PRR.2, and disable pullups
 by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
 (c) cable in the chipselect.
 
+        ======    ============    ===================
         Signal    Butterfly       Parport (DB-25)
-        ------    ---------       ---------------
-        VCC     = J400.VCC_EXT  = pin 7/D5
-        SELECT  = J400.PB0/nSS  = pin 17/C3,nSELECT
-        GND     = J400.GND      = pin 24/GND
+        ======    ============    ===================
+        VCC       J400.VCC_EXT    pin 7/D5
+        SELECT    J400.PB0/nSS    pin 17/C3,nSELECT
+        GND       J400.GND        pin 24/GND
+        ======    ============    ===================
 
 Or you could flash firmware making the AVR into an SPI slave (keeping the
 DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
 while letting either Linux or the AVR use the DataFlash.  There are plenty
 of spare parport pins to wire this one up, such as:
 
+        ======    =============   ===================
         Signal    Butterfly       Parport (DB-25)
-        ------    ---------       ---------------
-        SCK     = J403.PE4/USCK = pin 5/D3
-        MOSI    = J403.PE5/DI   = pin 6/D4
-        MISO    = J403.PE6/DO   = pin 12/S5,nPAPEROUT
-        GND     = J403.GND      = pin 22/GND
-
-        IRQ     = J402.PF4      = pin 10/S6,ACK
-        GND     = J402.GND(P2)  = pin 25/GND
+        ======    =============   ===================
+        SCK       J403.PE4/USCK   pin 5/D3
+        MOSI      J403.PE5/DI     pin 6/D4
+        MISO      J403.PE6/DO     pin 12/S5,nPAPEROUT
+        GND       J403.GND        pin 22/GND
 
+        IRQ       J402.PF4        pin 10/S6,ACK
+        GND       J402.GND(P2)    pin 25/GND
+        ======    =============   ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..06c34ea11bcf
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   spi-summary
+   spidev
+   butterfly
+   pxa2xx
+   spi-lm70llp
+   spi-sc18is602
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
index 551325b66b23..882d3cc72cc2 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
 PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
 This a mini howto on the pxa2xx_spi driver.  The driver turns a PXA2xx
 synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
 
 - Support for any PXA2xx SSP
 - SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
 -----------------------------------
 Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
 "platform device".  The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
 
-struct pxa2xx_spi_controller {
+  struct pxa2xx_spi_controller {
         u16 num_chipselect;
         u8 enable_dma;
-};
+  };
 
 The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
 slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
 
 NSSP MASTER SAMPLE
 ------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
 
-static struct resource pxa_spi_nssp_resources[] = {
+  static struct resource pxa_spi_nssp_resources[] = {
         [0] = {
                 .start  = __PREG(SSCR0_P(2)), /* Start address of NSSP */
                 .end    = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
                 .end    = IRQ_NSSP,
                 .flags  = IORESOURCE_IRQ,
         },
-};
+  };
 
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+  static struct pxa2xx_spi_controller pxa_nssp_master_info = {
         .num_chipselect = 1, /* Matches the number of chips attached to NSSP */
         .enable_dma = 1, /* Enables NSSP DMA */
-};
+  };
 
-static struct platform_device pxa_spi_nssp = {
+  static struct platform_device pxa_spi_nssp = {
         .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
         .id = 2, /* Bus number, MUST MATCH SSP number 1..n */
         .resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
         .dev = {
                 .platform_data = &pxa_nssp_master_info, /* Passed to driver */
         },
-};
+  };
 
-static struct platform_device *devices[] __initdata = {
+  static struct platform_device *devices[] __initdata = {
         &pxa_spi_nssp,
-};
+  };
 
-static void __init board_init(void)
-{
+  static void __init board_init(void)
+  {
         (void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+  }
 
 Declaring Slave Devices
 -----------------------
 Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
 using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
 
 Each slave device attached to the PXA must provide slave specific configuration
 information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
 will uses the configuration whenever the driver communicates with the slave
 device. All fields are optional.
 
-struct pxa2xx_spi_chip {
+::
+
+  struct pxa2xx_spi_chip {
         u8 tx_threshold;
         u8 rx_threshold;
         u8 dma_burst_size;
         u32 timeout;
         u8 enable_loopback;
         void (*cs_control)(u32 command);
-};
+  };
 
 The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
 used to configure the SSP hardware fifo.  These fields are critical to the
 performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
 
         .tx_threshold = 8,
         .rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
 "spi_board_info.controller_data" field. Below is a sample configuration using
 the PXA255 NSSP.
 
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+  /* Chip Select control for the CS8415A SPI slave device */
+  static void cs8415a_cs_control(u32 command)
+  {
         if (command & PXA2XX_CS_ASSERT)
                 GPCR(2) = GPIO_bit(2);
         else
                 GPSR(2) = GPIO_bit(2);
-}
+  }
 
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+  /* Chip Select control for the CS8405A SPI slave device */
+  static void cs8405a_cs_control(u32 command)
+  {
         if (command & PXA2XX_CS_ASSERT)
                 GPCR(3) = GPIO_bit(3);
         else
                 GPSR(3) = GPIO_bit(3);
-}
+  }
 
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+  static struct pxa2xx_spi_chip cs8415a_chip_info = {
         .tx_threshold = 8, /* SSP hardward FIFO threshold */
         .rx_threshold = 8, /* SSP hardward FIFO threshold */
         .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
         .timeout = 235, /* See Intel documentation */
         .cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+  static struct pxa2xx_spi_chip cs8405a_chip_info = {
         .tx_threshold = 8, /* SSP hardward FIFO threshold */
         .rx_threshold = 8, /* SSP hardward FIFO threshold */
         .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
         .timeout = 235, /* See Intel documentation */
         .cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+  static struct spi_board_info streetracer_spi_board_info[] __initdata = {
         {
                 .modalias = "cs8415a", /* Name of spi_driver for this device */
                 .max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
                 .controller_data = &cs8405a_chip_info, /* Master chip config */
                 .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
         },
-};
+  };
 
-static void __init streetracer_init(void)
-{
+  static void __init streetracer_init(void)
+  {
         spi_register_board_info(streetracer_spi_board_info,
                                 ARRAY_SIZE(streetracer_spi_board_info));
-}
+  }
 
 
 DMA and PIO I/O Support
@@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure.  The
 mode supports both coherent and stream based DMA mappings.
 
 The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
 
-if !enable_dma then
+  if !enable_dma then
         always use PIO transfers
 
-if spi_message.len > 8191 then
+  if spi_message.len > 8191 then
         print "rate limited" warning
         use PIO transfers
 
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+  if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
         use coherent DMA mode
 
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+  if rx_buf and tx_buf are aligned on 8 byte boundary then
         use streaming DMA mode
 
-otherwise
+  otherwise
         use PIO transfer
 
 THANKS TO
 ---------
 
 David Brownell and others for mentoring the development of this driver.
-
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
 spi_lm70llp :  LM70-LLP parport-to-SPI adapter
 ==============================================
 
 Supported board/chip:
+
   * National Semiconductor LM70 LLP evaluation board
+
     Datasheet: http://www.national.com/pf/LM/LM70.html
 
 Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
 
 The hardware interfacing on the LM70 LLP eval board is as follows:
 
+   ======== == =========   ==========
    Parallel                 LM70 LLP
-     Port      Direction   JP2 Header
-   ----------- --------- ----------------
+     Port   .  Direction   JP2 Header
+   ======== == =========   ==========
       D0     2      -         -
       D1     3     -->      V+   5
       D2     4     -->      V+   5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
       D7     9     -->      SI/O 5
      GND    25      -       GND  7
     Select  13     <--      SI/O 1
-   ----------- --------- ----------------
+   ======== == =========   ==========
 
 Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
 is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
 
 Thanks to
 ---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
index a45702865a38..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
 Kernel driver spi-sc18is602
 ===========================
 
 Supported chips:
+
   * NXP SI18IS602/602B/603
+
     Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
 
 Author:
@@ -17,7 +20,7 @@ kernel's SPI core subsystem.
 
 The driver does not probe for supported chips, since the SI18IS602/603 does not
 support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
+Please see Documentation/i2c/instantiating-devices.rst for details.
 
 
 Usage Notes
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
index 1a63194b74d7..f1daffe10d78 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
 Overview of Linux kernel SPI support
 ====================================
 
@@ -139,12 +140,14 @@ a command and then reading its response.
 
 There are two types of SPI driver, here called:
 
-  Controller drivers ... controllers may be built into System-On-Chip
+  Controller drivers ...
+        controllers may be built into System-On-Chip
         processors, and often support both Master and Slave roles.
         These drivers touch hardware registers and may use DMA.
         Or they can be PIO bitbangers, needing just GPIO pins.
 
-  Protocol drivers ... these pass messages through the controller
+  Protocol drivers ...
+        these pass messages through the controller
         driver to communicate with a Slave or Master device on the
         other side of an SPI link.
 
@@ -160,7 +163,7 @@ those two types of drivers.
 There is a minimal core of SPI programming interfaces, focussing on
 using the driver model to connect controller and protocol drivers using
 device tables provided by board specific initialization code.  SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
 
    /sys/devices/.../CTLR ... physical node for a given SPI controller
 
@@ -168,7 +171,7 @@ shows up in sysfs in several locations:
         chipselect C, accessed through CTLR.
 
    /sys/bus/spi/devices/spiB.C ... symlink to that physical
-        .../CTLR/spiB.C device
+        .../CTLR/spiB.C device
 
    /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
         that should be used with this device (for hotplug/coldplug)
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
 That information is normally provided by board-specific code, even for
 chips that do support some of automated discovery/enumeration.
 
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
 
 The first kind of information is a list of what SPI controllers exist.
 For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code.  This is because most SOCs have several
 SPI-capable controllers, and only the ones actually usable on a given
 board should normally be set up and registered.
 
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
 
         #include <mach/spi.h>   /* for mysoc_spi_data */
 
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
                 ...
         }
 
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
 
         #include <mach/spi.h>
 
@@ -269,8 +273,8 @@ same SOC controller is used.  For example, on one board SPI might use
 an external clock, where another derives the SPI clock from current
 settings of some master clock.
 
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
 
 The second kind of information is a list of what SPI slave devices exist
 on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
 
 Normally your arch/.../mach-*/board-*.c files would provide a small table
 listing the SPI devices on each board.  (This would typically be only a
-small handful.)  That might look like:
+small handful.)  That might look like::
 
         static struct ads7846_platform_data ads_info = {
                 .vref_delay_usecs       = 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
 
 Then your board initialization code would register that table with the SPI
 infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
 
         spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
 
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
 
 The widely used "card" style computers bundle memory, cpu, and little else
 onto a card that's maybe just thirty square centimeters.  On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
 about the devices on the mainboard into which such a card is plugged.  That
 certainly includes SPI devices hooked up through the card connectors!
 
 
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Developer boards often play by different rules than product boards, and one
 example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
 Most SPI drivers are currently kernel drivers, but there's also support
 for userspace drivers.  Here we talk only about kernel drivers.
 
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
 
         static struct spi_driver CHIP_driver = {
                 .driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP".  Your probe() code
 might look like this unless you're creating a device which is managing
 a bus (appearing under /sys/class/spi_master).
 
+::
+
         static int CHIP_probe(struct spi_device *spi)
         {
                 struct CHIP                     *chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
 Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
 to get the driver-private data allocated for that device.
 
+::
+
         struct spi_master       *master;
         struct CONTROLLER       *c;
 
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
 will reverse the effect of spi_register_master().
 
 
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
 
 Bus numbering is important, since that's how Linux identifies a given
 SPI bus (shared SCK, MOSI, MISO).  Valid bus numbers start at zero.  On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
 this as a non-static configuration (see above).
 
 
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
 
-    master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
         This sets up the device clock rate, SPI mode, and word sizes.
         Drivers may change the defaults provided by board_info, and then
         call spi_setup(spi) to invoke this routine.  It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
         change them right away ... otherwise drivers could corrupt I/O
         that's in progress for other SPI devices.
 
-                ** BUG ALERT:  for some reason the first version of
-                ** many spi_master drivers seems to get this wrong.
-                ** When you code setup(), ASSUME that the controller
-                ** is actively processing transfers for another device.
+        .. note::
+
+                BUG ALERT:  for some reason the first version of
+                many spi_master drivers seems to get this wrong.
+                When you code setup(), ASSUME that the controller
+                is actively processing transfers for another device.
 
-    master->cleanup(struct spi_device *spi)
+``master->cleanup(struct spi_device *spi)``
         Your controller driver may use spi_device.controller_state to hold
         state it dynamically associates with that device.  If you do that,
         be sure to provide the cleanup() method to free that state.
 
-    master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
         This will be called by the queue mechanism to signal to the driver
         that a message is coming in soon, so the subsystem requests the
         driver to prepare the transfer hardware by issuing this call.
         This may sleep.
 
-    master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
         This will be called by the queue mechanism to signal to the driver
         that there are no more messages pending in the queue and it may
         relax the hardware (e.g. by power management calls). This may sleep.
 
-    master->transfer_one_message(struct spi_master *master,
-                                 struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
         The subsystem calls the driver to transfer a single message while
         queuing transfers that arrive in the meantime. When the driver is
         finished with this message, it must call
         spi_finalize_current_message() so the subsystem can issue the next
         message. This may sleep.
 
-    master->transfer_one(struct spi_master *master, struct spi_device *spi,
-                         struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
         The subsystem calls the driver to transfer a single transfer while
         queuing transfers that arrive in the meantime. When the driver is
         finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
         not call your transfer_one callback.
 
         Return values:
-        negative errno: error
-        0: transfer is finished
-        1: transfer is still in progress
 
-    master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
-                              u8 hold_clk_cycles, u8 inactive_clk_cycles)
+        * negative errno: error
+        * 0: transfer is finished
+        * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
         This method allows SPI client drivers to request SPI master controller
         for configuring device specific CS setup, hold and inactive timing
         requirements.
 
-    DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
 
-    master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
         This must not sleep. Its responsibility is to arrange that the
         transfer happens and its complete() callback is issued. The two
         will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
         implemented.
 
 
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
 
 If you are happy with the standard queueing mechanism provided by the
 SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
 Contributors to Linux-SPI discussions include (in alphabetical order,
 by last name):
 
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
 SPI devices have a limited userspace API, supporting basic half-duplex
 read() and write() access to SPI slave devices.  Using ioctl() requests,
 full duplex transfers and device I/O configuration are also available.
 
+::
+
         #include <fcntl.h>
         #include <unistd.h>
         #include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
 busybox; it's less featureful, but often enough.)  For a SPI device with
 chipselect C on bus B, you should see:
 
-    /dev/spidevB.C ... character special device, major number 153 with
+    /dev/spidevB.C ...
+        character special device, major number 153 with
         a dynamically chosen minor device number.  This is the node
         that userspace programs will open, created by "udev" or "mdev".
 
-    /sys/devices/.../spiB.C ... as usual, the SPI device node will
+    /sys/devices/.../spiB.C ...
+        as usual, the SPI device node will
         be a child of its SPI master controller.
 
-    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+    /sys/class/spidev/spidevB.C ...
+        created when the "spidev" driver
         binds to that device.  (Directory or symlink, based on whether
         or not you enabled the "deprecated sysfs files" Kconfig option.)
 
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
 Several ioctl() requests let your driver read or override the device's current
 settings for data transfer parameters:
 
-    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+        pass a pointer to a byte which will
         return (RD) or assign (WR) the SPI transfer mode.  Use the constants
         SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
         (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
         Note that this request is limited to SPI mode flags that fit in a
         single byte.
 
-    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+        pass a pointer to a uin32_t
         which will return (RD) or assign (WR) the full SPI transfer mode,
         not limited to the bits that fit in one byte.
 
-    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+        pass a pointer to a byte
         which will return (RD) or assign (WR) the bit justification used to
         transfer SPI words.  Zero indicates MSB-first; other values indicate
         the less common LSB-first encoding.  In both cases the specified value
         is right-justified in each word, so that unused (TX) or undefined (RX)
         bits are in the MSBs.
 
-    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+        pass a pointer to
         a byte which will return (RD) or assign (WR) the number of bits in
         each SPI transfer word.  The value zero signifies eight bits.
 
-    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+        pass a pointer to a
         u32 which will return (RD) or assign (WR) the maximum SPI transfer
         speed, in Hz.  The controller can't necessarily assign that specific
         clock speed.
diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
index 1a660a39e3c0..993dd294b81b 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -1,8 +1,9 @@
-                Coresight CPU Debug Module
-                ==========================
+==========================
+Coresight CPU Debug Module
+==========================
 
-   Author:   Leo Yan <leo.yan@linaro.org>
-   Date:     April 5th, 2017
+   :Author:   Leo Yan <leo.yan@linaro.org>
+   :Date:     April 5th, 2017
 
 Introduction
 ------------
@@ -69,6 +70,7 @@ Before accessing debug registers, we should ensure the clock and power domain
 have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
 Debug registers', the debug registers are spread into two domains: the debug
 domain and the CPU domain.
+::
 
                                 +---------------+
                                 |               |
@@ -125,18 +127,21 @@ If you want to enable debugging functionality at boot time, you can add
 "coresight_cpu_debug.enable=1" to the kernel command line parameter.
 
 The driver also can work as module, so can enable the debugging when insmod
-module:
-# insmod coresight_cpu_debug.ko debug=1
+module::
+
+  # insmod coresight_cpu_debug.ko debug=1
 
 When boot time or insmod module you have not enabled the debugging, the driver
 uses the debugfs file system to provide a knob to dynamically enable or disable
 debugging:
 
-To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:
-# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
+To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::
+
+  # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
+
+To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::
 
-To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:
-# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
+  # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
 
 As explained in chapter "Clock and power domain", if you are working on one
 platform which has idle states to power off debug logic and the power
@@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
 interface (see Documentation/power/pm_qos_interface.rst for more
 details).  As specified in the PM QoS documentation the requested
 parameter will stay in effect until the file descriptor is released.
-For example:
+For example::
 
-# exec 3<> /dev/cpu_dma_latency; echo 0 >&3
-...
-Do some work...
-...
-# exec 3<>-
+  # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+  ...
+  Do some work...
+  ...
+  # exec 3<>-
 
 The same can also be done from an application program.
 
 Disable specific CPU's specific idle state from cpuidle sysfs (see
-Documentation/admin-guide/pm/cpuidle.rst):
-# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
+Documentation/admin-guide/pm/cpuidle.rst)::
 
+  # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
 
 Output format
 -------------
 
-Here is an example of the debugging output format:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug:  EDPCSR:  handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug:  EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug:  EDPCSR:  debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug:  EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+Here is an example of the debugging output format::
+
+  ARM external debug module:
+  coresight-cpu-debug 850000.debug: CPU[0]:
+  coresight-cpu-debug 850000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
+  coresight-cpu-debug 850000.debug:  EDPCSR:  handle_IPI+0x174/0x1d8
+  coresight-cpu-debug 850000.debug:  EDCIDSR: 00000000
+  coresight-cpu-debug 850000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+  coresight-cpu-debug 852000.debug: CPU[1]:
+  coresight-cpu-debug 852000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
+  coresight-cpu-debug 852000.debug:  EDPCSR:  debug_notifier_call+0x23c/0x358
+  coresight-cpu-debug 852000.debug:  EDCIDSR: 00000000
+  coresight-cpu-debug 852000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
index b027d61b27a6..72f4b7ef1bad 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,8 +1,9 @@
-                Coresight - HW Assisted Tracing on ARM
-                ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================
 
-   Author:   Mathieu Poirier <mathieu.poirier@linaro.org>
-   Date:     September 11th, 2014
+   :Author:   Mathieu Poirier <mathieu.poirier@linaro.org>
+   :Date:     September 11th, 2014
 
 Introduction
 ------------
@@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a memory buffer or
 creating an interface to the outside world where data can be transferred to a
 host without fear of filling up the onboard coresight memory buffer.
 
-At typical coresight system would look like this:
+At typical coresight system would look like this::
 
   *****************************************************************
  **************************** AMBA AXI  ****************************===||
@@ -95,15 +96,24 @@ Acronyms and Classification
 
 Acronyms:
 
-PTM:     Program Trace Macrocell
-ETM:     Embedded Trace Macrocell
-STM:     System trace Macrocell
-ETB:     Embedded Trace Buffer
-ITM:     Instrumentation Trace Macrocell
-TPIU:    Trace Port Interface Unit
-TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
-TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
-CTI:     Cross Trigger Interface
+PTM:
+    Program Trace Macrocell
+ETM:
+    Embedded Trace Macrocell
+STM:
+    System trace Macrocell
+ETB:
+    Embedded Trace Buffer
+ITM:
+    Instrumentation Trace Macrocell
+TPIU:
+     Trace Port Interface Unit
+TMC-ETR:
+        Trace Memory Controller, configured as Embedded Trace Router
+TMC-ETF:
+        Trace Memory Controller, configured as Embedded Trace FIFO
+CTI:
+    Cross Trigger Interface
 
 Classification:
 
@@ -118,7 +128,7 @@ Misc:
 
 
 Device Tree Bindings
-----------------------
+--------------------
 
 See Documentation/devicetree/bindings/arm/coresight.txt for details.
 
@@ -133,79 +143,79 @@ The coresight framework provides a central point to represent, configure and
 manage coresight devices on a platform.  Any coresight compliant device can
 register with the framework for as long as they use the right APIs:
 
-struct coresight_device *coresight_register(struct coresight_desc *desc);
-void coresight_unregister(struct coresight_device *csdev);
+.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc);
+.. c:function:: void coresight_unregister(struct coresight_device *csdev);
 
-The registering function is taking a "struct coresight_device *csdev" and
-register the device with the core framework.  The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
+The registering function is taking a ``struct coresight_desc *desc`` and
+register the device with the core framework. The unregister function takes
+a reference to a ``struct coresight_device *csdev`` obtained at registration time.
 
 If everything goes well during the registration process the new devices will
-show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
+show up under /sys/bus/coresight/devices, as showns here for a TC2 platform::
 
-root:~# ls /sys/bus/coresight/devices/
-replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
-20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
-root:~#
+    root:~# ls /sys/bus/coresight/devices/
+    replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
+    20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
+    root:~#
 
-The functions take a "struct coresight_device", which looks like this:
+The functions take a ``struct coresight_device``, which looks like this::
 
-struct coresight_desc {
-        enum coresight_dev_type type;
-        struct coresight_dev_subtype subtype;
-        const struct coresight_ops *ops;
-        struct coresight_platform_data *pdata;
-        struct device *dev;
-        const struct attribute_group **groups;
-};
+    struct coresight_desc {
+            enum coresight_dev_type type;
+            struct coresight_dev_subtype subtype;
+            const struct coresight_ops *ops;
+            struct coresight_platform_data *pdata;
+            struct device *dev;
+            const struct attribute_group **groups;
+    };
 
 
 The "coresight_dev_type" identifies what the device is, i.e, source link or
 sink while the "coresight_dev_subtype" will characterise that type further.
 
-The "struct coresight_ops" is mandatory and will tell the framework how to
+The ``struct coresight_ops`` is mandatory and will tell the framework how to
 perform base operations related to the components, each component having
-a different set of requirement.  For that "struct coresight_ops_sink",
-"struct coresight_ops_link" and "struct coresight_ops_source" have been
+a different set of requirement. For that ``struct coresight_ops_sink``,
+``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been
 provided.
 
-The next field, "struct coresight_platform_data *pdata" is acquired by calling
-"of_get_coresight_platform_data()", as part of the driver's _probe routine and
-"struct device *dev" gets the device reference embedded in the "amba_device":
+The next field ``struct coresight_platform_data *pdata`` is acquired by calling
+``of_get_coresight_platform_data()``, as part of the driver's _probe routine and
+``struct device *dev`` gets the device reference embedded in the ``amba_device``::
 
-static int etm_probe(struct amba_device *adev, const struct amba_id *id)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+    static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+    {
+     ...
+     ...
+     drvdata->dev = &adev->dev;
+     ...
+    }
 
 Specific class of device (source, link, or sink) have generic operations
-that can be performed on them (see "struct coresight_ops").  The
-"**groups" is a list of sysfs entries pertaining to operations
+that can be performed on them (see ``struct coresight_ops``). The ``**groups``
+is a list of sysfs entries pertaining to operations
 specific to that component only.  "Implementation defined" customisations are
 expected to be accessed and controlled using those entries.
 
-
 Device Naming scheme
-------------------------
+--------------------
+
 The devices that appear on the "coresight" bus were named the same as their
 parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.
 Thus the names were based on the Linux Open Firmware layer naming convention,
 which follows the base physical address of the device followed by the device
-type. e.g:
+type. e.g::
 
-root:~# ls /sys/bus/coresight/devices/
- 20010000.etf  20040000.funnel      20100000.stm     22040000.etm
- 22140000.etm  230c0000.funnel      23240000.etm     20030000.tpiu
- 20070000.etr  20120000.replicator  220c0000.funnel
- 23040000.etm  23140000.etm         23340000.etm
+    root:~# ls /sys/bus/coresight/devices/
+     20010000.etf  20040000.funnel      20100000.stm     22040000.etm
+     22140000.etm  230c0000.funnel      23240000.etm     20030000.tpiu
+     20070000.etr  20120000.replicator  220c0000.funnel
+     23040000.etm  23140000.etm         23340000.etm
 
 However, with the introduction of ACPI support, the names of the real
 devices are a bit cryptic and non-obvious. Thus, a new naming scheme was
 introduced to use more generic names based on the type of the device. The
-following rules apply:
+following rules apply::
 
   1) Devices that are bound to CPUs, are named based on the CPU logical
      number.
@@ -220,11 +230,11 @@ following rules apply:
 
         e.g, tmc_etf0, tmc_etr0, funnel0, funnel1
 
-Thus, with the new scheme the devices could appear as :
+Thus, with the new scheme the devices could appear as ::
 
-root:~# ls /sys/bus/coresight/devices/
- etm0     etm1     etm2         etm3  etm4      etm5      funnel0
- funnel1  funnel2  replicator0  stm0  tmc_etf0  tmc_etr0  tpiu0
+    root:~# ls /sys/bus/coresight/devices/
+     etm0     etm1     etm2         etm3  etm4      etm5      funnel0
+     funnel1  funnel2  replicator0  stm0  tmc_etf0  tmc_etr0  tpiu0
 
 Some of the examples below might refer to old naming scheme and some
 to the newer scheme, to give a confirmation that what you see on your
@@ -234,9 +244,12 @@ the system under specified locations.
 How to use the tracer modules
 -----------------------------
 
-There are two ways to use the Coresight framework: 1) using the perf cmd line
-tools and 2) interacting directly with the Coresight devices using the sysFS
-interface.  Preference is given to the former as using the sysFS interface
+There are two ways to use the Coresight framework:
+
+1. using the perf cmd line tools.
+2. interacting directly with the Coresight devices using the sysFS interface.
+
+Preference is given to the former as using the sysFS interface
 requires a deep understanding of the Coresight HW.  The following sections
 provide details on using both methods.
 
@@ -245,107 +258,107 @@ provide details on using both methods.
 Before trace collection can start, a coresight sink needs to be identified.
 There is no limit on the amount of sinks (nor sources) that can be enabled at
 any given moment.  As a generic operation, all device pertaining to the sink
-class will have an "active" entry in sysfs:
-
-root:/sys/bus/coresight/devices# ls
-replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
-20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink  status  trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+class will have an "active" entry in sysfs::
+
+    root:/sys/bus/coresight/devices# ls
+    replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
+    20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
+    root:/sys/bus/coresight/devices# ls 20010000.etb
+    enable_sink  status  trigger_cntr
+    root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+    root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+    1
+    root:/sys/bus/coresight/devices#
 
 At boot time the current etm3x driver will configure the first address
 comparator with "_stext" and "_etext", essentially tracing any instruction
 that falls within that range.  As such "enabling" a source will immediately
-trigger a trace capture:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth:          0x2000
-Status:         0x1
-RAM read ptr:   0x0
-RAM wrt ptr:    0x19d3   <----- The write pointer is moving
-Trigger cnt:    0x0
-Control:        0x1
-Flush status:   0x0
-Flush ctrl:     0x2001
-root:/sys/bus/coresight/devices#
-
-Trace collection is stopped the same way:
-
-root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices#
-
-The content of the ETB buffer can be harvested directly from /dev:
-
-root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
-of=~/cstrace.bin
-
-64+0 records in
-64+0 records out
-32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
-root:/sys/bus/coresight/devices#
+trigger a trace capture::
+
+    root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
+    root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
+    1
+    root:/sys/bus/coresight/devices# cat 20010000.etb/status
+    Depth:          0x2000
+    Status:         0x1
+    RAM read ptr:   0x0
+    RAM wrt ptr:    0x19d3   <----- The write pointer is moving
+    Trigger cnt:    0x0
+    Control:        0x1
+    Flush status:   0x0
+    Flush ctrl:     0x2001
+    root:/sys/bus/coresight/devices#
+
+Trace collection is stopped the same way::
+
+    root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
+    root:/sys/bus/coresight/devices#
+
+The content of the ETB buffer can be harvested directly from /dev::
+
+    root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
+    of=~/cstrace.bin
+    64+0 records in
+    64+0 records out
+    32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
+    root:/sys/bus/coresight/devices#
 
 The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
 
 Following is a DS-5 output of an experimental loop that increments a variable up
 to a certain value.  The example is simple and yet provides a glimpse of the
 wealth of possibilities that coresight provides.
-
-Info                                    Tracing enabled
-Instruction     106378866       0x8026B53C      E52DE004        false   PUSH     {lr}
-Instruction     0       0x8026B540      E24DD00C        false   SUB      sp,sp,#0xc
-Instruction     0       0x8026B544      E3A03000        false   MOV      r3,#0
-Instruction     0       0x8026B548      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Timestamp                                       Timestamp: 17106715833
-Instruction     319     0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Instruction     9       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Instruction     10      0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
-Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
-Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
-Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
-Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
-Instruction     6       0x8026B560      EE1D3F30        false   MRC      p15,#0x0,r3,c13,c0,#1
-Instruction     0       0x8026B564      E1A0100D        false   MOV      r1,sp
-Instruction     0       0x8026B568      E3C12D7F        false   BIC      r2,r1,#0x1fc0
-Instruction     0       0x8026B56C      E3C2203F        false   BIC      r2,r2,#0x3f
-Instruction     0       0x8026B570      E59D1004        false   LDR      r1,[sp,#4]
-Instruction     0       0x8026B574      E59F0010        false   LDR      r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction     0       0x8026B578      E592200C        false   LDR      r2,[r2,#0xc]
-Instruction     0       0x8026B57C      E59221D0        false   LDR      r2,[r2,#0x1d0]
-Instruction     0       0x8026B580      EB07A4CF        true    BL       {pc}+0x1e9344 ; 0x804548c4
-Info                                    Tracing enabled
-Instruction     13570831        0x8026B584      E28DD00C        false   ADD      sp,sp,#0xc
-Instruction     0       0x8026B588      E8BD8000        true    LDM      sp!,{pc}
-Timestamp                                       Timestamp: 17107041535
+::
+
+    Info                                    Tracing enabled
+    Instruction     106378866       0x8026B53C      E52DE004        false   PUSH     {lr}
+    Instruction     0       0x8026B540      E24DD00C        false   SUB      sp,sp,#0xc
+    Instruction     0       0x8026B544      E3A03000        false   MOV      r3,#0
+    Instruction     0       0x8026B548      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Timestamp                                       Timestamp: 17106715833
+    Instruction     319     0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Instruction     9       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Instruction     10      0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
+    Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
+    Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
+    Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
+    Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
+    Instruction     6       0x8026B560      EE1D3F30        false   MRC      p15,#0x0,r3,c13,c0,#1
+    Instruction     0       0x8026B564      E1A0100D        false   MOV      r1,sp
+    Instruction     0       0x8026B568      E3C12D7F        false   BIC      r2,r1,#0x1fc0
+    Instruction     0       0x8026B56C      E3C2203F        false   BIC      r2,r2,#0x3f
+    Instruction     0       0x8026B570      E59D1004        false   LDR      r1,[sp,#4]
+    Instruction     0       0x8026B574      E59F0010        false   LDR      r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+    Instruction     0       0x8026B578      E592200C        false   LDR      r2,[r2,#0xc]
+    Instruction     0       0x8026B57C      E59221D0        false   LDR      r2,[r2,#0x1d0]
+    Instruction     0       0x8026B580      EB07A4CF        true    BL       {pc}+0x1e9344 ; 0x804548c4
+    Info                                    Tracing enabled
+    Instruction     13570831        0x8026B584      E28DD00C        false   ADD      sp,sp,#0xc
+    Instruction     0       0x8026B588      E8BD8000        true    LDM      sp!,{pc}
+    Timestamp                                       Timestamp: 17107041535
 
 2) Using perf framework:
 
@@ -370,19 +383,18 @@ A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is
 listed along with configuration options within forward slashes '/'.  Since a
 Coresight system will typically have more than one sink, the name of the sink to
 work with needs to be specified as an event option.
-On newer kernels the available sinks are listed in sysFS under:
-($SYSFS)/bus/event_source/devices/cs_etm/sinks/
+On newer kernels the available sinks are listed in sysFS under
+($SYSFS)/bus/event_source/devices/cs_etm/sinks/::
 
         root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls
         tmc_etf0  tmc_etr0  tpiu0
 
 On older kernels, this may need to be found from the list of coresight devices,
-available under ($SYSFS)/bus/coresight/devices/:
+available under ($SYSFS)/bus/coresight/devices/::
 
         root:~# ls /sys/bus/coresight/devices/
          etm0     etm1     etm2         etm3  etm4      etm5      funnel0
          funnel1  funnel2  replicator0  stm0  tmc_etf0  tmc_etr0  tpiu0
-
         root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program
 
 As mentioned above in section "Device Naming scheme", the names of the devices could
@@ -395,14 +407,14 @@ to use for the trace session.
 
 More information on the above and other example on how to use Coresight with
 the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub
-repository [3].
+repository [#third]_.
 
 2.1) AutoFDO analysis using the perf tools:
 
 perf can be used to record and analyze trace of programs.
 
 Execution can be recorded using 'perf record' with the cs_etm event,
-specifying the name of the sink to record to, e.g:
+specifying the name of the sink to record to, e.g::
 
     perf record -e cs_etm/@tmc_etr0/u --per-thread
 
@@ -421,12 +433,14 @@ Generating coverage files for Feedback Directed Optimization: AutoFDO
 
 'perf inject' accepts the --itrace option in which case tracing data is
 removed and replaced with the synthesized events. e.g.
+::
 
         perf inject --itrace --strip -i perf.data -o perf.data.new
 
 Below is an example of using ARM ETM for autoFDO.  It requires autofdo
 (https://github.com/google/autofdo) and gcc version 5.  The bubble
 sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
+::
 
         $ gcc-5 -O3 sort.c -o sort
         $ taskset -c 2 ./sort
@@ -455,28 +469,30 @@ difference is that clients are driving the trace capture rather
 than the program flow through the code.
 
 As with any other CoreSight component, specifics about the STM tracer can be
-found in sysfs with more information on each entry being found in [1]:
+found in sysfs with more information on each entry being found in [#first]_::
 
-root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
-enable_source   hwevent_select  port_enable     subsystem       uevent
-hwevent_enable  mgmt            port_select     traceid
-root@genericarmv8:~#
+    root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
+    enable_source   hwevent_select  port_enable     subsystem       uevent
+    hwevent_enable  mgmt            port_select     traceid
+    root@genericarmv8:~#
 
 Like any other source a sink needs to be identified and the STM enabled before
-being used:
+being used::
 
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source
+    root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
+    root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source
 
 From there user space applications can request and use channels using the devfs
-interface provided for that purpose by the generic STM API:
+interface provided for that purpose by the generic STM API::
+
+    root@genericarmv8:~# ls -l /dev/stm0
+    crw-------    1 root     root       10,  61 Jan  3 18:11 /dev/stm0
+    root@genericarmv8:~#
+
+Details on how to use the generic STM API can be found here [#second]_.
 
-root@genericarmv8:~# ls -l /dev/stm0
-crw-------    1 root     root       10,  61 Jan  3 18:11 /dev/stm0
-root@genericarmv8:~#
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
 
-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst
 
-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index f60079259669..e3060eedb22d 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -125,7 +125,8 @@ of ftrace. Here is a list of some of the key files:
 
         This file holds the output of the trace in a human
         readable format (described below). Note, tracing is temporarily
-        disabled while this file is being read (opened).
+        disabled when the file is open for reading. Once all readers
+        are closed, tracing is re-enabled.
 
   trace_pipe:
 
@@ -139,8 +140,9 @@ of ftrace. Here is a list of some of the key files:
         will not be read again with a sequential read. The
         "trace" file is static, and if the tracer is not
         adding more data, it will display the same
-        information every time it is read. This file will not
-        disable tracing while being read.
+        information every time it is read. Unlike the
+        "trace" file, opening this file for reading will not
+        temporarily disable tracing.
 
   trace_options:
 
@@ -3153,7 +3155,10 @@ different. The trace is live.
 
 
 Note, reading the trace_pipe file will block until more input is
-added.
+added. This is contrary to the trace file. If any process opened
+the trace file for reading, it will actually disable tracing and
+prevent new entries from being added. The trace_pipe file does
+not have this limitation.
 
 trace entries
 -------------
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..b7891cb1ab4d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@ Linux Tracing Technologies
    intel_th
    stm
    sys-t
+   coresight
+   coresight-cpu-debug
diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst
index d0874327f301..94a6499742ac 100644
--- a/Documentation/translations/it_IT/process/changes.rst
+++ b/Documentation/translations/it_IT/process/changes.rst
@@ -26,16 +26,15 @@ Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi
 usando, il comando indicato dovrebbe dirvelo.
 
 Questa lista presume che abbiate già un kernel Linux funzionante.  In aggiunta,
-non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete un
-modem ISDN, per esempio, probabilmente non dovreste preoccuparvi di
-isdn4k-utils.
+non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una
+PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
 
 ====================== =================  ========================================
         Programma       Versione minima       Comando per verificare la versione
 ====================== =================  ========================================
 GNU C                  4.6                gcc --version
 GNU make               3.81               make --version
-binutils               2.20               ld -v
+binutils               2.21               ld -v
 flex                   2.5.35             flex --version
 bison                  2.0                bison --version
 util-linux             2.10o              fdformat --version
@@ -49,7 +48,6 @@ btrfs-progs            0.18               btrfsck
 pcmciautils            004                pccardctl -V
 quota-tools            3.09               quota -V
 PPP                    2.4.0              pppd --version
-isdn4k-utils           3.1pre1            isdnctrl 2>&1|grep version
 nfs-utils              1.0.5              showmount --version
 procps                 3.2.0              ps --version
 oprofile               0.9                oprofiled --version
@@ -81,10 +79,7 @@ Per compilare il kernel vi servirà GNU make 3.81 o successivo.
 Binutils
 --------
 
-Il sistema di compilazione, dalla versione 4.13,  per la produzione dei passi
-intermedi, si è convertito all'uso di *thin archive* (`ar T`) piuttosto che
-all'uso del *linking* incrementale (`ld -r`). Questo richiede binutils 2.20 o
-successivo.
+Per generare il kernel è necessario avere Binutils 2.21 o superiore.
 
 pkg-config
 ----------
@@ -286,11 +281,6 @@ col seguente comando::
 
   mknod /dev/ppp c 108 0
 
-Isdn4k-utils
-------------
-
-Per via della modifica del campo per il numero di telefono, il pacchetto
-isdn4k-utils dev'essere ricompilato o (preferibilmente) aggiornato.
 
 NFS-utils
 ---------
@@ -456,10 +446,6 @@ PPP
 
 - <ftp://ftp.samba.org/pub/ppp/>
 
-Isdn4k-utils
-------------
-
-- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
 
 NFS-utils
 ---------
diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst
index 44e6077730e8..1db5a1082389 100644
--- a/Documentation/translations/it_IT/process/howto.rst
+++ b/Documentation/translations/it_IT/process/howto.rst
@@ -129,7 +129,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che
                 https://www.ozlabs.org/~akpm/stuff/tpp.txt
 
         "Linux kernel patch submission format"
-                http://linux.yyz.us/patch-format.html
+                https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
 
   :ref:`Documentation/translations/it_IT/process/stable-api-nonsense.rst <it_stable_api_nonsense>`
 
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst
index 7d7ea92c5c5a..cba1f8cb61ed 100644
--- a/Documentation/translations/it_IT/process/submitting-patches.rst
+++ b/Documentation/translations/it_IT/process/submitting-patches.rst
@@ -868,7 +868,7 @@ Andrew Morton, "La patch perfetta" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
 
 Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
-  <http://linux.yyz.us/patch-format.html>
+  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
 
 Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
   <http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
index ad979c3c06a6..dd0c3280ba5a 100644
--- a/Documentation/translations/ja_JP/SubmittingPatches
+++ b/Documentation/translations/ja_JP/SubmittingPatches
@@ -693,7 +693,7 @@ Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
 
 Jeff Garzik, "Linux kernel patch submission format".
-  <http://linux.yyz.us/patch-format.html>
+  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
 
 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
   <http://www.kroah.com/log/2005/03/31/>
diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
index 2621b770a745..73ebdab4ced7 100644
--- a/Documentation/translations/ja_JP/howto.rst
+++ b/Documentation/translations/ja_JP/howto.rst
@@ -139,7 +139,7 @@ linux-api@vger.kernel.org ��る��を勧���。
        "The Perfect Patch"
                 http://www.ozlabs.org/~akpm/stuff/tpp.txt
        "Linux kernel patch submission format"
-                http://linux.yyz.us/patch-format.html
+                https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
 
   :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
     ��ファイル�カー�ル�中��変� API を����������識的
diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
index bcd63731b80a..b3f51b19de7c 100644
--- a/Documentation/translations/ko_KR/howto.rst
+++ b/Documentation/translations/ko_KR/howto.rst
@@ -135,7 +135,7 @@ mtk.manpages@gmail.com� 메�테�너�게 보낼 것� 권장한다.
         https://www.ozlabs.org/~akpm/stuff/tpp.txt
 
     "Linux kernel patch submission format"
-        http://linux.yyz.us/patch-format.html
+        https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
 
    :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
     � 문서는 ���으로 커�� 불변하는 API를 갖지 않�� 결정한
diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
index 4e373d128d98..5b0164132c71 100644
--- a/Documentation/translations/zh_CN/arm64/booting.txt
+++ b/Documentation/translations/zh_CN/arm64/booting.txt
@@ -67,8 +67,8 @@ RAM，或�能使用对这个设备已知的 RAM 信�，还�能是引导装
 必�性: 强制
 
 设备树数��（dtb）必须 8 字节对�，且大��能超过 2MB。由于设备树
-数��将在使能缓存的情况下以 2MB 粒度被映射，故其�能被置于带任�
-特定属性被映射的 2MB 区域内。
+数��将在使能缓存的情况下以 2MB 粒度被映射，故其�能被置于必须以特定
+属性映射的2M区域内。
 
 注： v4.2 之�的版本�时�求设备树数��被置于从内核映�以下
 text_offset 字节处算起第一个 512MB 内。
diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst
index 5b671178b17b..a8e6ab818983 100644
--- a/Documentation/translations/zh_CN/process/howto.rst
+++ b/Documentation/translations/zh_CN/process/howto.rst
@@ -113,7 +113,7 @@ Linux内核代�中包�有大�的文档。这些文档对于学习如何与
 
     "Linux kernel patch submission format"
 
-        http://linux.yyz.us/patch-format.html
+        https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
 
   :ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst <cn_stable_api_nonsense>`
     论�内核为什么特��包括稳定的内核内部API，也就是说�包括�这样的特
@@ -146,14 +146,18 @@ Linux内核代�中包�有大�的文档。这些文档对于学习如何与
   :ref:`Documentation/process/applying-patches.rst <applying_patches>`
     关于补�是什么以�如何将它打在��内核开�分支上的好介�
 
-内核还拥有大�从代�自动生�的文档。它包�内核内部API的全�介�以�如何
-妥善处�加�的规则。生�的文档会放在 Documentation/DocBook/目录下。在内
-核��的主目录中使用以下��命令将会分别生�PDF�Postscript�HTML和手册
-页等��格�的文档::
+内核还拥有大�从代�自动生�或者从 ReStructuredText(ReST) 标记生�的文档，
+比如这个文档，它包�内核内部API的全�介�以�如何妥善处�加�的规则。所有
+这些文档都�以通过�行以下命令从内核代�中生�为PDF或HTML文档::
 
     make pdfdocs
     make htmldocs
 
+ReST格�的文档会生�在 Documentation/output. 目录中。
+它们也�以用下列命令生� LaTeX 和 ePub 格�文档::
+
+    make latexdocs
+    make epubdocs
 
 如何�为内核开�者
 ------------------
diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst
index 437c23b367bb..1bb4271ab420 100644
--- a/Documentation/translations/zh_CN/process/submitting-patches.rst
+++ b/Documentation/translations/zh_CN/process/submitting-patches.rst
@@ -652,7 +652,7 @@ Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
 
 Jeff Garzik, "Linux kernel patch submission format".
-  <http://linux.yyz.us/patch-format.html>
+  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
 
 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
   <http://www.kroah.com/log/linux/maintainer.html>
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..57cba81865e2
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+   :maxdepth: 1
+
+
+   w1-generic.rst
+   w1-netlink.rst
+   masters/index
+   slaves/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..17ebe8f660cd 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
 Kernel driver ds2482
 ====================
 
 Supported chips:
+
   * Maxim DS2482-100, Maxim DS2482-800
+
     Prefix: 'ds2482'
+
     Addresses scanned: None
+
     Datasheets:
-        http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
-        http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
 
 Author: Ben Gardner <bgardner@wabtec.com>
 
@@ -23,9 +29,11 @@ General Remarks
 ---------------
 
 Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
 However, the device cannot be detected without writing to the i2c bus, so no
 detection is done. You should instantiate the device explicitly.
 
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
 
+  $ modprobe ds2482
+  $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
 Kernel driver ds2490
 ====================
 
 Supported chips:
+
   * Maxim DS2490 based
 
 Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
 low-level operational chip.
 
 Notes and limitations.
+
 - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
 - The 5V strong pullup is supported with a minimum of 5.9mA and a
   maximum of 30.4 mA.  (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
   reattaching would clear the problem.  usbmon output in the guest and
   host did not explain the problem.  My guess is a bug in either qemu
   or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   ds2482
+   ds2490
+   mxc-w1
+   omap-hdq
+   w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1
deleted file mode 100644
index 38be1ad65532..000000000000
--- a/Documentation/w1/masters/mxc-w1
+++ /dev/null
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
-  * Freescale MX27, MX31 and probably other i.MX SoCs
-    Datasheets:
-        http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
-        http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
-        Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
-        Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst
new file mode 100644
index 000000000000..334f9893103f
--- /dev/null
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+  * Freescale MX27, MX31 and probably other i.MX SoCs
+
+    Datasheets:
+
+        - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+        - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+        Originally based on Freescale code, prepared for mainline by
+        Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
 ========================================
 
 Supported chips:
 ================
-        HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
 
 A useful link about HDQ basics:
 ===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
 Please note to load both the modules with a different ID if required, but note
 that the ID used should be same for both master and slave driver loading.
 
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+  insmod omap_hdq.ko W1_ID=2
+  inamod w1_bq27000.ko F_ID=2
 
 The driver also supports 1-wire mode. In this mode, there is no need to
 pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
 Kernel driver w1-gpio
 =====================
 
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
 Example (mach-at91)
 -------------------
 
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
+
+  #include <linux/gpio/machine.h>
+  #include <linux/w1-gpio.h>
 
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+  static struct gpiod_lookup_table foo_w1_gpiod_table = {
         .dev_id = "w1-gpio",
         .table = {
                 GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
                         GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
         },
-};
+  };
 
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+  static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
         .ext_pullup_enable_pin  = -EINVAL,
-};
+  };
 
-static struct platform_device foo_w1_device = {
+  static struct platform_device foo_w1_device = {
         .name                   = "w1-gpio",
         .id                     = -1,
         .dev.platform_data      = &foo_w1_gpio_pdata,
-};
+  };
 
-...
+  ...
         at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
         at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
         gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   w1_ds2406
+   w1_ds2413
+   w1_ds2423
+   w1_ds2438
+   w1_ds28e04
+   w1_ds28e17
+   w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..d3e68266084f 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
 w1_ds2406 kernel driver
 =======================
 
 Supported chips:
+
   * Maxim DS2406 (and other family 0x12) addressable switches
 
 Author: Scott Alfter <scott@alfter.us>
@@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us>
 Description
 -----------
 
-The w1_ds2406 driver allows connected devices to be switched on and off. 
+The w1_ds2406 driver allows connected devices to be switched on and off.
 These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
 not supported.  In TSOC-6 form, the DS2406 provides two switch outputs and
 can be provided with power on a dedicated input.  In TO-92 form, it provides
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
 Kernel driver w1_ds2413
 =======================
 
 Supported chips:
+
   * Maxim DS2413 1-Wire Dual Channel Addressable Switch
 
 supported family codes:
+
+        ================        ====
         W1_FAMILY_DS2413        0x3A
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -20,11 +25,13 @@ Reading state
 The "state" file provides one-byte value which is in the same format as for
 the chip PIO_ACCESS_READ command (refer the datasheet for details):
 
+======== =============================================================
 Bit 0:   PIOA Pin State
 Bit 1:   PIOA Output Latch State
 Bit 2:   PIOB Pin State
 Bit 3:   PIOB Output Latch State
 Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
 
 This file is readonly.
 
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
 It is writable, you can write one-byte value to this sysfs file.
 Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
 
+======== ======================================
 Bit 0:   PIOA
 Bit 1:   PIOB
 Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
 
 
 The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423
deleted file mode 100644
index 3f98b505a0ee..000000000000
--- a/Documentation/w1/slaves/w1_ds2423
+++ /dev/null
@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
-  * Maxim DS2423 based counter devices.
-
-supported family codes:
-        W1_THERM_DS2423 0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 000000000000..755d659ad997
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+  * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+        =============== ====
+        W1_THERM_DS2423 0x1D
+        =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+  00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
 =======================
 
 Supported chips:
+
   * Maxim DS2438 Smart Battery Monitor
 
 supported family codes:
+        ================        ====
         W1_FAMILY_DS2438        0x26
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
 command of the chip.
 
 Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+    general purpose A/D input (VAD)
+vdd:
+    battery input (VDD)
 
 After the voltage conversion the value is returned as decimal ASCII.
 Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e04
 ========================
 
 Supported chips:
+
   * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
 
 supported family codes:
+
+        =================       ====
         W1_FAMILY_DS28E04       0x1C
+        =================       ====
 
 Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
 
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..e2d9f96d8f2c 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e17
 ========================
 
 Supported chips:
+
   * Maxim DS28E17 1-Wire-to-I2C Master Bridge
 
 supported family codes:
+
+        =================  ====
         W1_FAMILY_DS28E17  0x19
+        =================  ====
 
 Author: Jan Kandziora <jjj@gmx.de>
 
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
 connected to a "native" I2C bus master.
 
 
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
-        SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+  SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+          SYMLINK+="i2c-$attr{name}"
+
 may be used to create stable /dev/i2c- entries based on the unique id of the
 DS28E17 chip.
 
@@ -65,4 +70,3 @@ structure is created.
 
 
 See https://github.com/ianka/w1_ds28e17 for even more information.
-
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
 Kernel driver w1_therm
-====================
+======================
 
 Supported chips:
+
   * Maxim ds18*20 based temperature sensors.
   * Maxim ds1825 based temperature sensors.
 
@@ -13,12 +15,16 @@ Description
 
 w1_therm provides basic temperature conversion for ds18*20 devices, and the
 ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+====================    ====
 W1_THERM_DS18S20        0x10
 W1_THERM_DS1822         0x22
 W1_THERM_DS18B20        0x28
 W1_THERM_DS1825         0x3B
 W1_THERM_DS28EA00       0x42
+====================    ====
 
 Support is provided through the sysfs w1_slave file.  Each open and
 read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
 In case the detection of parasite devices using this command fails
 (seems to be the case with some DS18S20) the strong pullup can
 be force-enabled.
+
 If the strong pullup is enabled, the master's strong pullup will be
 driven when the conversion is taking place, provided the master driver
 does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
 The 1-wire bus is a simple master-slave bus that communicates via a single
 signal wire (plus ground, so two wires).
 
@@ -12,14 +14,16 @@ communication with slaves.
 All w1 slave devices must be connected to a w1 bus master device.
 
 Example w1 master devices:
-    DS9490 usb device
-    W1-over-GPIO
-    DS2482 (i2c to w1 bridge)
-    Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+    - DS9490 usb device
+    - W1-over-GPIO
+    - DS2482 (i2c to w1 bridge)
+    - Emulated devices, such as a RS232 converter, parallel port adapter, etc
 
 
 What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
 When a w1 master driver registers with the w1 subsystem, the following occurs:
 
  - sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
 
 
 W1 device families
-------------------------------------------------------------------
+------------------
+
 Slave devices are handled by a driver written for a family of w1 devices.
 
 A family driver populates a struct w1_family_ops (see w1_family.h) and
 registers with the w1 subsystem.
 
 Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+  - (ds18?20 thermal sensor family driver)
     provides temperature reading function which is bound to ->rbin() method
     of the above w1_family_ops structure.
 
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+  - driver for simple 64bit memory cell provides ID reading method.
 
 You can call above methods by reading appropriate sysfs files.
 
 
 What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
 
 The driver for w1 bus master must provide at minimum two functions.
 
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
 
 
 w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx>  - A directory for a found device. The format is family-serial
-bus                - (standard) symlink to the w1 bus
-driver             - (standard) symlink to the w1 driver
-w1_master_add      - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
-                   - (rw) maximum number of slaves to search for at a time
-w1_master_name     - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup   - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove   - (rw) manually remove a slave device
-w1_master_search   - (rw) the number of searches left to do,
-                     -1=continual (default)
-w1_master_slave_count
-                   - (ro) the number of slaves found
-w1_master_slaves   - (ro) the names of the slaves, one per line
-w1_master_timeout  - (ro) the delay in seconds between searches
-w1_master_timeout_us
-                   - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx>         A directory for a found device. The format is
+                          family-serial
+bus                       (standard) symlink to the w1 bus
+driver                    (standard) symlink to the w1 driver
+w1_master_add             (rw) manually register a slave device
+w1_master_attempts        (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name            (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup          (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove          (rw) manually remove a slave device
+w1_master_search          (rw) the number of searches left to do,
+                          -1=continual (default)
+w1_master_slave_count     (ro) the number of slaves found
+w1_master_slaves          (ro) the names of the slaves, one per line
+w1_master_timeout         (ro) the delay in seconds between searches
+w1_master_timeout_us      (ro) the delay in microseconds beetwen searches
+========================= =====================================================
 
 If you have a w1 bus that never changes (you don't add or remove devices),
 you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
 w1_master_attempts by 1.
 
 w1 slave sysfs interface
-------------------------------------------------------------------
-bus                - (standard) symlink to the w1 bus
-driver             - (standard) symlink to the w1 driver
-name               - the device name, usually the same as the directory name
-w1_slave           - (optional) a binary file whose meaning depends on the
-                     family driver
-rw                 - (optional) created for slave devices which do not have
-                     appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus                 (standard) symlink to the w1 bus
+driver              (standard) symlink to the w1 driver
+name                the device name, usually the same as the directory name
+w1_slave            (optional) a binary file whose meaning depends on the
+                    family driver
+rw                  (optional) created for slave devices which do not have
+                    appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
index 94ad4c420828..aaa13243a5e4 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
 
-
-Message types.
+Message types
 =============
 
 There are three types of messages between w1 core and userspace:
+
 1. Events. They are generated each time a new master or slave device
-        is found either due to automatic or requested search.
+   is found either due to automatic or requested search.
 2. Userspace commands.
 3. Replies to userspace commands.
 
 
-Protocol.
+Protocol
 ========
 
-[struct cn_msg] - connector header.
+::
+
+  [struct cn_msg] - connector header.
         Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+  [struct w1_netlink_msg] - w1 netlink header.
         __u8 type       - message type.
                         W1_LIST_MASTERS
                                 list current bus masters
@@ -40,7 +44,7 @@ Protocol.
                 } mst;
         } id;
 
-[struct w1_netlink_cmd] - command for given master or slave device.
+  [struct w1_netlink_cmd] - command for given master or slave device.
         __u8 cmd        - command opcode.
                         W1_CMD_READ     - read command
                         W1_CMD_WRITE    - write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
 Currently replies to userspace commands are only generated for read
 command request. One reply is generated exactly for one w1_netlink_cmd
 read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
 
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+  [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+  cn_msg.len = sizeof(struct w1_netlink_msg) +
              sizeof(struct w1_netlink_cmd) +
              cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+  w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+  w1_netlink_cmd.len = cmd->len;
 
 Replies to W1_LIST_MASTERS should send a message back to the userspace
 which will contain list of all registered master ids in the following
-format:
+format::
 
         cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
         w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
                 number of masters multiplied by 4 (u32 size))
         id0 ... idN
 
-        Each message is at most 4k in size, so if number of master devices
-        exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
 
 W1 search and alarm search commands.
-request:
-[cn_msg]
-  [w1_netlink_msg type = W1_MASTER_CMD
-        id is equal to the bus master id to use for searching]
-  [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
 
-reply:
+request::
+
+  [cn_msg]
+    [w1_netlink_msg type = W1_MASTER_CMD
+        id is equal to the bus master id to use for searching]
+    [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
+
   [cn_msg, ack = 1 and increasing, 0 means the last message,
-        seq is equal to the request seq]
+        seq is equal to the request seq]
   [w1_netlink_msg type = W1_MASTER_CMD]
   [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
         len is equal to number of IDs multiplied by 8]
   [64bit-id0 ... 64bit-idN]
+
 Length in each header corresponds to the size of the data behind it, so
 w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
-        Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+  w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+  cn_msg->len = sizeof(struct w1_netlink_msg) +
               sizeof(struct w1_netlink_cmd) +
               N*8;
 
-W1 reset command.
-[cn_msg]
-  [w1_netlink_msg type = W1_MASTER_CMD
-        id is equal to the bus master id to use for searching]
-  [w1_netlink_cmd cmd = W1_CMD_RESET]
+W1 reset command::
 
+  [cn_msg]
+    [w1_netlink_msg type = W1_MASTER_CMD
+        id is equal to the bus master id to use for searching]
+    [w1_netlink_cmd cmd = W1_CMD_RESET]
 
-Command status replies.
+
+Command status replies
 ======================
 
 Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
 even if there were errors, only length mismatch interrupts message processing.
 
 
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
 =======================================================
 
 When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
 and next w1_netlink_msg header processing started.
 
 
-Connector [1] specific documentation.
+Connector [1] specific documentation
 ====================================
 
 Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
 acknowledge number is set to seq+1.
 
 
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
 
 1. Documentation/driver-api/connector.rst
 2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+   This archive includes userspace application w1d.c which uses
+   read/write/search commands for all master/slave devices found on the bus.
diff --git a/MAINTAINERS b/MAINTAINERS
index 8147615da48c..1c735e5e2702 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -658,7 +658,7 @@ ALI1563 I2C DRIVER
 M:      Rudolf Marek <r.marek@assembler.cz>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/busses/i2c-ali1563
+F:      Documentation/i2c/busses/i2c-ali1563.rst
 F:      drivers/i2c/busses/i2c-ali1563.c
 
 ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -1573,8 +1573,8 @@ R:	Suzuki K Poulose <suzuki.poulose@arm.com>
 L:      linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 S:      Maintained
 F:      drivers/hwtracing/coresight/*
-F:      Documentation/trace/coresight.txt
-F:      Documentation/trace/coresight-cpu-debug.txt
+F:      Documentation/trace/coresight.rst
+F:      Documentation/trace/coresight-cpu-debug.rst
 F:      Documentation/devicetree/bindings/arm/coresight.txt
 F:      Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
 F:      Documentation/ABI/testing/sysfs-bus-coresight-devices-*
@@ -4080,7 +4080,7 @@ L:	samba-technical@lists.samba.org (moderated for non-subscribers)
 W:      http://linux-cifs.samba.org/
 T:      git git://git.samba.org/sfrench/cifs-2.6.git
 S:      Supported
-F:      Documentation/filesystems/cifs/
+F:      Documentation/admin-guide/cifs/
 F:      fs/cifs/
 
 COMPACTPCI HOTPLUG CORE
@@ -4936,7 +4936,9 @@ M:	Jonathan Corbet <corbet@lwn.net>
 L:      linux-doc@vger.kernel.org
 S:      Maintained
 F:      Documentation/
+F:      scripts/documentation-file-ref-check
 F:      scripts/kernel-doc
+F:      scripts/sphinx-pre-install
 X:      Documentation/ABI/
 X:      Documentation/firmware-guide/acpi/
 X:      Documentation/devicetree/
@@ -4952,6 +4954,14 @@ L:	linux-doc@vger.kernel.org
 S:      Maintained
 F:      Documentation/translations/it_IT
 
+DOCUMENTATION SCRIPTS
+M:      Mauro Carvalho Chehab <mchehab@kernel.org>
+L:      linux-doc@vger.kernel.org
+S:      Maintained
+F:      scripts/documentation-file-ref-check
+F:      scripts/sphinx-pre-install
+F:      Documentation/sphinx/parse-headers.pl
+
 DONGWOON DW9714 LENS VOICE COIL DRIVER
 M:      Sakari Ailus <sakari.ailus@linux.intel.com>
 L:      linux-media@vger.kernel.org
@@ -6312,7 +6322,7 @@ FLEXTIMER FTM-QUADDEC DRIVER
 M:      Patrick Havelange <patrick.havelange@essensium.com>
 L:      linux-iio@vger.kernel.org
 S:      Maintained
-F:      Documentation/ABI/testing/sysfs-bus-counter-ftm-quadddec
+F:      Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec
 F:      Documentation/devicetree/bindings/counter/ftm-quaddec.txt
 F:      drivers/counter/ftm-quaddec.c
 
@@ -6734,7 +6744,7 @@ L:	linux-i2c@vger.kernel.org
 S:      Supported
 F:      drivers/i2c/muxes/i2c-mux-gpio.c
 F:      include/linux/platform_data/i2c-mux-gpio.h
-F:      Documentation/i2c/muxes/i2c-mux-gpio
+F:      Documentation/i2c/muxes/i2c-mux-gpio.rst
 
 GENERIC HDLC (WAN) DRIVERS
 M:      Krzysztof Halasa <khc@pm.waw.pl>
@@ -7483,14 +7493,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
 M:      Ajay Gupta <ajayg@nvidia.com>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/busses/i2c-nvidia-gpu
+F:      Documentation/i2c/busses/i2c-nvidia-gpu.rst
 F:      drivers/i2c/busses/i2c-nvidia-gpu.c
 
 I2C MUXES
 M:      Peter Rosin <peda@axentia.se>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/i2c-topology
+F:      Documentation/i2c/i2c-topology.rst
 F:      Documentation/i2c/muxes/
 F:      Documentation/devicetree/bindings/i2c/i2c-mux*
 F:      Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7510,8 +7520,8 @@ I2C OVER PARALLEL PORT
 M:      Jean Delvare <jdelvare@suse.com>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/busses/i2c-parport
-F:      Documentation/i2c/busses/i2c-parport-light
+F:      Documentation/i2c/busses/i2c-parport.rst
+F:      Documentation/i2c/busses/i2c-parport-light.rst
 F:      drivers/i2c/busses/i2c-parport.c
 F:      drivers/i2c/busses/i2c-parport-light.c
 
@@ -7545,7 +7555,7 @@ I2C-TAOS-EVM DRIVER
 M:      Jean Delvare <jdelvare@suse.com>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/busses/i2c-taos-evm
+F:      Documentation/i2c/busses/i2c-taos-evm.rst
 F:      drivers/i2c/busses/i2c-taos-evm.c
 
 I2C-TINY-USB DRIVER
@@ -7559,19 +7569,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
 M:      Jean Delvare <jdelvare@suse.com>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
-F:      Documentation/i2c/busses/i2c-ali1535
-F:      Documentation/i2c/busses/i2c-ali1563
-F:      Documentation/i2c/busses/i2c-ali15x3
-F:      Documentation/i2c/busses/i2c-amd756
-F:      Documentation/i2c/busses/i2c-amd8111
-F:      Documentation/i2c/busses/i2c-i801
-F:      Documentation/i2c/busses/i2c-nforce2
-F:      Documentation/i2c/busses/i2c-piix4
-F:      Documentation/i2c/busses/i2c-sis5595
-F:      Documentation/i2c/busses/i2c-sis630
-F:      Documentation/i2c/busses/i2c-sis96x
-F:      Documentation/i2c/busses/i2c-via
-F:      Documentation/i2c/busses/i2c-viapro
+F:      Documentation/i2c/busses/i2c-ali1535.rst
+F:      Documentation/i2c/busses/i2c-ali1563.rst
+F:      Documentation/i2c/busses/i2c-ali15x3.rst
+F:      Documentation/i2c/busses/i2c-amd756.rst
+F:      Documentation/i2c/busses/i2c-amd8111.rst
+F:      Documentation/i2c/busses/i2c-i801.rst
+F:      Documentation/i2c/busses/i2c-nforce2.rst
+F:      Documentation/i2c/busses/i2c-piix4.rst
+F:      Documentation/i2c/busses/i2c-sis5595.rst
+F:      Documentation/i2c/busses/i2c-sis630.rst
+F:      Documentation/i2c/busses/i2c-sis96x.rst
+F:      Documentation/i2c/busses/i2c-via.rst
+F:      Documentation/i2c/busses/i2c-viapro.rst
 F:      drivers/i2c/busses/i2c-ali1535.c
 F:      drivers/i2c/busses/i2c-ali1563.c
 F:      drivers/i2c/busses/i2c-ali15x3.c
@@ -7600,7 +7610,7 @@ M:	Seth Heasley <seth.heasley@intel.com>
 M:      Neil Horman <nhorman@tuxdriver.com>
 L:      linux-i2c@vger.kernel.org
 F:      drivers/i2c/busses/i2c-ismt.c
-F:      Documentation/i2c/busses/i2c-ismt
+F:      Documentation/i2c/busses/i2c-ismt.rst
 
 I2C/SMBUS STUB DRIVER
 M:      Jean Delvare <jdelvare@suse.com>
@@ -8350,7 +8360,7 @@ M:	linux-wimax@intel.com
 L:      wimax@linuxwimax.org (subscribers-only)
 S:      Supported
 W:      http://linuxwimax.org
-F:      Documentation/wimax/README.i2400m
+F:      Documentation/admin-guide/wimax/i2400m.rst
 F:      drivers/net/wimax/i2400m/
 F:      include/uapi/linux/wimax/i2400m.h
 
@@ -8635,7 +8645,7 @@ L:	jfs-discussion@lists.sourceforge.net
 W:      http://jfs.sourceforge.net/
 T:      git git://github.com/kleikamp/linux-shaggy.git
 S:      Maintained
-F:      Documentation/filesystems/jfs.txt
+F:      Documentation/admin-guide/jfs.rst
 F:      fs/jfs/
 
 JME NETWORK DRIVER
@@ -8978,7 +8988,7 @@ F:	kernel/kprobes.c
 KS0108 LCD CONTROLLER DRIVER
 M:      Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
 S:      Maintained
-F:      Documentation/auxdisplay/ks0108
+F:      Documentation/admin-guide/auxdisplay/ks0108.rst
 F:      drivers/auxdisplay/ks0108.c
 F:      include/linux/ks0108.h
 
@@ -9567,7 +9577,7 @@ F:	Documentation/networking/mac80211-injection.txt
 F:      include/net/mac80211.h
 F:      net/mac80211/
 F:      drivers/net/wireless/mac80211_hwsim.[ch]
-F:      Documentation/networking/mac80211_hwsim/README
+F:      Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
 
 MAILBOX API
 M:      Jassi Brar <jassisinghbrar@gmail.com>
@@ -10344,7 +10354,7 @@ L:	linux-i2c@vger.kernel.org
 S:      Supported
 F:      drivers/i2c/busses/i2c-mlxcpld.c
 F:      drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F:      Documentation/i2c/busses/i2c-mlxcpld
+F:      Documentation/i2c/busses/i2c-mlxcpld.rst
 
 MELLANOX MLXCPLD LED DRIVER
 M:      Vadim Pasternak <vadimp@mellanox.com>
@@ -11954,7 +11964,7 @@ M:	Andrew Lunn <andrew@lunn.ch>
 L:      linux-i2c@vger.kernel.org
 S:      Maintained
 F:      Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F:      Documentation/i2c/busses/i2c-ocores
+F:      Documentation/i2c/busses/i2c-ocores.rst
 F:      drivers/i2c/busses/i2c-ocores.c
 F:      include/linux/platform_data/i2c-ocores.h
 
@@ -12077,7 +12087,7 @@ L:	netdev@vger.kernel.org
 S:      Supported
 F:      lib/packing.c
 F:      include/linux/packing.h
-F:      Documentation/packing.txt
+F:      Documentation/core-api/packing.rst
 
 PADATA PARALLEL EXECUTION MECHANISM
 M:      Steffen Klassert <steffen.klassert@secunet.com>
@@ -14276,7 +14286,7 @@ F:	net/sctp/
 SCx200 CPU SUPPORT
 M:      Jim Cromie <jim.cromie@gmail.com>
 S:      Odd Fixes
-F:      Documentation/i2c/busses/scx200_acb
+F:      Documentation/i2c/busses/scx200_acb.rst
 F:      arch/x86/platform/scx200/
 F:      drivers/watchdog/scx200_wdt.c
 F:      drivers/i2c/busses/scx200*
@@ -15915,7 +15925,7 @@ M:	Viresh Kumar <viresh.kumar@linaro.org>
 M:      Javi Merino <javi.merino@kernel.org>
 L:      linux-pm@vger.kernel.org
 S:      Supported
-F:      Documentation/thermal/cpu-cooling-api.rst
+F:      Documentation/driver-api/thermal/cpu-cooling-api.rst
 F:      drivers/thermal/cpu_cooling.c
 F:      include/linux/cpu_cooling.h
 
@@ -16438,7 +16448,7 @@ F:	drivers/hid/hid-udraw-ps3.c
 UFS FILESYSTEM
 M:      Evgeniy Dushistov <dushistov@mail.ru>
 S:      Maintained
-F:      Documentation/filesystems/ufs.txt
+F:      Documentation/admin-guide/ufs.rst
 F:      fs/ufs/
 
 UHID USERSPACE HID IO DRIVER:
@@ -17358,7 +17368,7 @@ M:	linux-wimax@intel.com
 L:      wimax@linuxwimax.org (subscribers-only)
 S:      Supported
 W:      http://linuxwimax.org
-F:      Documentation/wimax/README.wimax
+F:      Documentation/admin-guide/wimax/wimax.rst
 F:      include/linux/wimax/debug.h
 F:      include/net/wimax.h
 F:      include/uapi/linux/wimax.h
diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig
index 68489d1f00bb..b8313a04422d 100644
--- a/drivers/auxdisplay/Kconfig
+++ b/drivers/auxdisplay/Kconfig
@@ -97,7 +97,7 @@ config CFAG12864B
           say Y. You also need the ks0108 LCD Controller driver.
 
           For help about how to wire your LCD to the parallel port,
-          check Documentation/auxdisplay/cfag12864b
+          check Documentation/admin-guide/auxdisplay/cfag12864b.rst
 
           Depends on the x86 arch and the framebuffer support.
 
diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
index e232fa948833..79b8df258371 100644
--- a/drivers/hwmon/atxp1.c
+++ b/drivers/hwmon/atxp1.c
@@ -5,7 +5,7 @@
  *
  * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
  * not auto-detected by the driver and must be instantiated explicitly.
- * See Documentation/i2c/instantiating-devices for more information.
+ * See Documentation/i2c/instantiating-devices.rst for more information.
  */
 
 #include <linux/kernel.h>
diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
index 6eff14fe395d..af01f763f7d1 100644
--- a/drivers/hwmon/smm665.c
+++ b/drivers/hwmon/smm665.c
@@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
         if (rv != -ENXIO) {
                 /*
                  * We expect ENXIO to reflect NACK
-                 * (per Documentation/i2c/fault-codes).
+                 * (per Documentation/i2c/fault-codes.rst).
                  * Everything else is an error.
                  */
                 dev_dbg(&client->dev,
diff --git a/drivers/hwtracing/coresight/Kconfig b/drivers/hwtracing/coresight/Kconfig
index 14638db4991d..7a9f5fb08330 100644
--- a/drivers/hwtracing/coresight/Kconfig
+++ b/drivers/hwtracing/coresight/Kconfig
@@ -106,7 +106,7 @@ config CORESIGHT_CPU_DEBUG
           can quickly get to know program counter (PC), secure state,
           exception level, etc. Before use debugging functionality, platform
           needs to ensure the clock domain and power domain are enabled
-          properly, please refer Documentation/trace/coresight-cpu-debug.txt
+          properly, please refer Documentation/trace/coresight-cpu-debug.rst
           for detailed description and the example for usage.
 
 endif
diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
index abedd55a1264..1474e57ecafc 100644
--- a/drivers/i2c/Kconfig
+++ b/drivers/i2c/Kconfig
@@ -54,7 +54,7 @@ config I2C_CHARDEV
           Say Y here to use i2c-* device files, usually found in the /dev
           directory on your system.  They make it possible to have user-space
           programs use the I2C bus.  Information on how to do this is
-          contained in the file <file:Documentation/i2c/dev-interface>.
+          contained in the file <file:Documentation/i2c/dev-interface.rst>.
 
           This support is also available as a module.  If so, the module 
           will be called i2c-dev.
@@ -107,7 +107,7 @@ config I2C_STUB
           especially for certain kinds of sensor chips.
 
           If you do build this module, be sure to read the notes and warnings
-          in <file:Documentation/i2c/i2c-stub>.
+          in <file:Documentation/i2c/i2c-stub.rst>.
 
           If you don't know what to do here, definitely say N.
 
diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
index f8c77edf70d0..a362245cc558 100644
--- a/drivers/i2c/busses/Kconfig
+++ b/drivers/i2c/busses/Kconfig
@@ -1206,7 +1206,7 @@ config I2C_PARPORT
           and makes it easier to add support for new devices.
 
           An adapter type parameter is now mandatory.  Please read the file
-          Documentation/i2c/busses/i2c-parport for details.
+          Documentation/i2c/busses/i2c-parport.rst for details.
 
           Another driver exists, named i2c-parport-light, which doesn't depend
           on the parport driver.  This is meant for embedded systems. Don't say
diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
index 2e08b4722dc4..36e9559f880c 100644
--- a/drivers/i2c/busses/i2c-i801.c
+++ b/drivers/i2c/busses/i2c-i801.c
@@ -77,7 +77,7 @@
  * SMBus Host Notify                    yes
  * Interrupt processing                 yes
  *
- * See the file Documentation/i2c/busses/i2c-i801 for details.
+ * See the file Documentation/i2c/busses/i2c-i801.rst for details.
  */
 
 #include <linux/interrupt.h>
diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
index c82e78f57386..37347c93e8e0 100644
--- a/drivers/i2c/busses/i2c-taos-evm.c
+++ b/drivers/i2c/busses/i2c-taos-evm.c
@@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
                         /*
                          * Voluntarily dropping error code of kstrtou8 since all
                          * error code that it could return are invalid according
-                         * to Documentation/i2c/fault-codes.
+                         * to Documentation/i2c/fault-codes.rst.
                          */
                         if (kstrtou8(p + 1, 16, &data->byte))
                                 return -EPROTO;
diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
index 9c440fa6a3dd..72b300174cb8 100644
--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
                         dev_warn(&adapter->dev,
                                 "This adapter will soon drop class based instantiation of devices. "
                                 "Please make sure client 0x%02x gets instantiated by other means. "
-                                "Check 'Documentation/i2c/instantiating-devices' for details.\n",
+                                "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
                                 info.addr);
 
                 dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
@@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
         if (adapter->class == I2C_CLASS_DEPRECATED) {
                 dev_dbg(&adapter->dev,
                         "This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
-                        "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
+                        "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
                         driver->driver.name);
                 return 0;
         }
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index 8f99c005458a..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -693,9 +693,9 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
  * Varies depending on bus type of the device. As there is no device
  * here, call probe directly. For information on device registration
  * i2c:
- * Documentation/i2c/writing-clients
+ * Documentation/i2c/writing-clients.rst
  * spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
  */
 static const struct iio_sw_device_ops iio_dummy_device_ops = {
         .probe = iio_dummy_probe,
diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
index 225a8df1d4e9..367497914c10 100644
--- a/drivers/rtc/rtc-ds1374.c
+++ b/drivers/rtc/rtc-ds1374.c
@@ -14,7 +14,7 @@
  */
 /*
  * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
- * recommened in .../Documentation/i2c/writing-clients section
+ * recommended in .../Documentation/i2c/writing-clients.rst section
  * "Sending and receiving", using SMBus level communication is preferred.
  */
 
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 0f0fdb57198f..6f7fdcbb9151 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -546,7 +546,7 @@ config SPI_PXA2XX
         help
           This enables using a PXA2xx or Sodaville SSP port as a SPI master
           controller. The driver can be configured to use any SSP port and
-          additional documentation can be found a Documentation/spi/pxa2xx.
+          additional documentation can be found a Documentation/spi/pxa2xx.rst.
 
 config SPI_PXA2XX_PCI
         def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
  * with a battery powered AVR microcontroller and lots of goodies.  You
  * can use GCC to develop firmware for this.
  *
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
  * and use this custom parallel port cable.
  */
 
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
  * available (on page 4) here:
  *  http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
  *
- * Also see Documentation/spi/spi-lm70llp.  The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst.  The SPI<->parport code here is
  * (heavily) based on spi-butterfly by David Brownell.
  *
  * The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
         help
           Say Y here if you have one of Hypercope's active PCI ISDN cards
           Champ, Ergo and Metro. You will then get a module called hysdn.
-          Please read the file <file:Documentation/isdn/README.hysdn> for more
+          Please read the file <file:Documentation/isdn/hysdn.rst> for more
           information.
 
 config HYSDN_CAPI
diff --git a/fs/cifs/export.c b/fs/cifs/export.c
index ce8b7f677c58..eb0bb8ca8e63 100644
--- a/fs/cifs/export.c
+++ b/fs/cifs/export.c
@@ -24,7 +24,7 @@
  */
 
  /*
-  * See Documentation/filesystems/nfs/Exporting
+  * See Documentation/filesystems/nfs/exporting.rst
   * and examples in fs/exportfs
   *
   * Since cifs is a network file system, an "fsid" must be included for
diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c
index f0e549783caf..09bc68708d28 100644
--- a/fs/exportfs/expfs.c
+++ b/fs/exportfs/expfs.c
@@ -7,7 +7,7 @@
  * and for mapping back from file handles to dentries.
  *
  * For details on why we do all the strange and hairy things in here
- * take a look at Documentation/filesystems/nfs/Exporting.
+ * take a look at Documentation/filesystems/nfs/exporting.rst.
  */
 #include <linux/exportfs.h>
 #include <linux/fs.h>
diff --git a/fs/isofs/export.c b/fs/isofs/export.c
index 85a9093769a9..35768a63fb1d 100644
--- a/fs/isofs/export.c
+++ b/fs/isofs/export.c
@@ -10,7 +10,7 @@
  *
  * The following files are helpful:
  *
- *     Documentation/filesystems/nfs/Exporting
+ *     Documentation/filesystems/nfs/exporting.rst
  *     fs/exportfs/expfs.c.
  */
 
diff --git a/fs/jfs/Kconfig b/fs/jfs/Kconfig
index 22a273bd4648..05cb0e8e4382 100644
--- a/fs/jfs/Kconfig
+++ b/fs/jfs/Kconfig
@@ -5,7 +5,7 @@ config JFS_FS
         select CRC32
         help
           This is a port of IBM's Journaled Filesystem .  More information is
-          available in the file <file:Documentation/filesystems/jfs.txt>.
+          available in the file <file:Documentation/admin-guide/jfs.rst>.
 
           If you do not intend to use the JFS filesystem, say N.
 
diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c
index 960f9a3c012d..a5612abc0936 100644
--- a/fs/orangefs/file.c
+++ b/fs/orangefs/file.c
@@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file,
  * Change the file pointer position for an instance of an open file.
  *
  * \note If .llseek is overriden, we must acquire lock as described in
- *       Documentation/filesystems/Locking.
+ *       Documentation/filesystems/locking.rst.
  *
  * Future upgrade could support SEEK_DATA and SEEK_HOLE but would
  * require much changes to the FS
diff --git a/fs/orangefs/orangefs-kernel.h b/fs/orangefs/orangefs-kernel.h
index 572dd29fbd54..34a6c99fa29b 100644
--- a/fs/orangefs/orangefs-kernel.h
+++ b/fs/orangefs/orangefs-kernel.h
@@ -246,7 +246,7 @@ struct orangefs_read_options {
 extern struct orangefs_stats orangefs_stats;
 
 /*
- * NOTE: See Documentation/filesystems/porting for information
+ * NOTE: See Documentation/filesystems/porting.rst for information
  * on implementing FOO_I and properly accessing fs private data
  */
 static inline struct orangefs_inode_s *ORANGEFS_I(struct inode *inode)
diff --git a/fs/ufs/Kconfig b/fs/ufs/Kconfig
index fcb41516ea59..6d30adb6b890 100644
--- a/fs/ufs/Kconfig
+++ b/fs/ufs/Kconfig
@@ -9,7 +9,7 @@ config UFS_FS
           this file system as well. Saying Y here will allow you to read from
           these partitions; if you also want to write to them, say Y to the
           experimental "UFS file system write support", below. Please read the
-          file <file:Documentation/filesystems/ufs.txt> for more information.
+          file <file:Documentation/admin-guide/ufs.rst> for more information.
 
           The recently released UFS2 variant (used in FreeBSD 5.x) is
           READ-ONLY supported.
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 9451011ac014..10090f11ab95 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -151,7 +151,7 @@ struct dentry_operations {
 
 /*
  * Locking rules for dentry_operations callbacks are to be found in
- * Documentation/filesystems/Locking. Keep it updated!
+ * Documentation/filesystems/locking.rst. Keep it updated!
  *
  * FUrther descriptions are found in Documentation/filesystems/vfs.rst.
  * Keep it updated too!
diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index 0d3037419bc7..cf6571fc9c01 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -139,7 +139,7 @@ struct fid {
  * @get_parent:     find the parent of a given directory
  * @commit_metadata: commit metadata changes to stable storage
  *
- * See Documentation/filesystems/nfs/Exporting for details on how to use
+ * See Documentation/filesystems/nfs/exporting.rst for details on how to use
  * this interface correctly.
  *
  * encode_fh:
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index fa5552c2307b..c0a78c069117 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  *
  * The return codes from the @master_xfer{_atomic} fields should indicate the
  * type of error code that occurred during the transfer, as documented in the
- * Kernel Documentation file Documentation/i2c/fault-codes.
+ * Kernel Documentation file Documentation/i2c/fault-codes.rst.
  */
 struct i2c_algorithm {
         /*
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
  *
  * Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
  *
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
  */
 
 /**
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
          * platform characterization. This value is relative to the
          * rest of the weights so a cooling device whose weight is
          * double that of another cooling device is twice as
-         * effective. See Documentation/thermal/sysfs-api.rst for more
+         * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
          * information.
          */
         int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
         /*
          * This is a bit mask that gives the binding relation between this
          * thermal zone and cdev, for a particular trip point.
-         * See Documentation/thermal/sysfs-api.rst for more information.
+         * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
          */
         int trip_mask;
 
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6b03012750da..81dc91760b23 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1245,7 +1245,7 @@ sub dump_enum($$) {
     # strip #define macros inside enums
     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
 
-    if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) {
+    if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
         $declaration_name = $1;
         my $members = $2;
         my %_members;
@@ -1580,6 +1580,7 @@ sub dump_function($$) {
     $prototype =~ s/__must_check +//;
     $prototype =~ s/__weak +//;
     $prototype =~ s/__sched +//;
+    $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
     $prototype =~ s/__attribute__\s*\(\(
             (?: