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.
 
 You'll still find a handful of annoying conflicts against other trees,
 mostly tied to the last RST conversions; resolutions are straightforward
 and the linux-next ones are good.
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCAAdFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl1/J4IACgkQF0NaE2wM
 flhYogf9EgYozCe8RocSq+JjJpZOSFjIGDQv+GwTjOBIdqgO9tSIaY/p0wSkYKil
 jYXyMDF+Xwr8podsUep2F7akBM7j9XJ+XBGJcfOna0ypC9xoejMgWt9fU3YvaWge
 dQJxIQ/iwkDlKNx6uOYgKysLUWFS0EP/nzPhqBo4bZZzhugvrR46D/nQqFNmGihd
 l9yLalJtP5mC0XRUv3hpdAFFFKxdC0R3BGOel2V+slSClp0LEgpdMAuMaKydEDI3
 Ch9ZpIp8fB8kqONCs9/X6083WRsDOMe28KgeGrGHo4Jla6u51QBLQjSVKttFv7xk
 051yNJwDWMxgl+A4gyNLDPXM7Gd7HQ==
 =v4dp
 -----END PGP SIGNATURE-----

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🔒 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
  ...

.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>
+Quentin Perret <qperret@qperret.net> <quentin.perret@arm.com>
-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>
 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>

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

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

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

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.

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`

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

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

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
+- Zwane Mwaikambo
-Amrut Joshi
+- Andi Kleen
-Shobhit Dayal
+- Amrut Joshi
-Sergey Vlasov
+- Shobhit Dayal
-Richard Hughes
+- Sergey Vlasov
-Yury Umanets
+- Richard Hughes
-Mark Hamzy (for some of the early cifs IPv6 work)
+- Yury Umanets
-Domen Puncer
+- Mark Hamzy (for some of the early cifs IPv6 work)
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Domen Puncer
-Vince Negri and Dave Stahl (for finding an important caching bug)
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Adrian Bunk (kcalloc cleanups)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
-Miklos Szeredi 
+- Adrian Bunk (kcalloc cleanups)
-Kazeon team for various fixes especially for 2.4 version.
+- Miklos Szeredi
-Asser Ferno (Change Notify support)
+- Kazeon team for various fixes especially for 2.4 version.
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Asser Ferno (Change Notify support)
-Gunter Kukkukk (testing and suggestions for support of old servers)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Igor Mammedov (DFS support)
+- Gunter Kukkukk (testing and suggestions for support of old servers)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Igor Mammedov (DFS support)
-Scott Lovenberg
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Scott Lovenberg
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Shirish Pargaonkar (for many ACL patches over the years)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Shirish Pargaonkar (for many ACL patches over the years)
-Paulo Alcantara
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Long Li (some great work on RDMA, SMB Direct)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
 
 
 Test case and Bug Report contributors

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

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`

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

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) Additional use cases can be optimized to use "compounding" (e.g.
-(e.g. open/query/close and open/setinfo/close) to reduce the number
+   open/query/close and open/setinfo/close) to reduce the number of
-of roundtrips to the server and improve performance. Various cases
+   roundtrips to the server and improve performance. Various cases
-(stat, statfs, create, unlink, mkdir) already have been improved by
+   (stat, statfs, create, unlink, mkdir) already have been improved by
-using compounding but more can be done.  In addition we could significantly
+   using compounding but more can be done. In addition we could
-reduce redundant opens by using deferred close (with handle caching leases)
+   significantly reduce redundant opens by using deferred close (with
-and better using reference counters on file handles.
+   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
+   will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.   
+   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
+   mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
+   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
+   (passthrough ioctl/fsctl is now implemented in cifs.ko to allow
-various SMB3 fsctls and query info and set info calls directly from user space)
+   sending various SMB3 fsctls and query info and set info calls
-Add tools to make setting various non-POSIX metadata attributes easier
+   directly from user space) Add tools to make setting various non-POSIX
-from tools (e.g. extending what was done in smb-info tool).
+   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
+   secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
+   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
+   can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
+   support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
+   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 - 
+3) Additional performance testing and optimization using iozone and similar -
-there are some easy changes that can be done to parallelize sequential writes,
+   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 
+   and when signing is disabled to request larger read sizes (larger than
-negotiated size) and send larger write sizes to modern servers.
+   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
+   against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
+   to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+   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
+   the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
+   problems that static analyzers will point out in the future).

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

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

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=continue
-errors=remount-ro(*)	Remount the filesystem read-only on an error.
+                        Keep going on a filesystem error.
-errors=panic		Panic and halt the machine if an error occurs.
+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
+uid=value
-gid=value	Override on-disk gid with specified value
+                Override on-disk uid with specified value
-umask=value	Override on-disk umask with specified octal value.  For
+gid=value
-		directories, the execute bit will be set if the corresponding
+                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=minlen, discard/nodiscard(*)
-discard		The discard/TRIM commands are sent to the underlying
+                This enables/disables the use of discard/TRIM commands.
-nodiscard(*)	block device when blocks are freed. This is useful for SSD
+		The discard/TRIM commands are sent to the underlying
-		devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl
+                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.

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>

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
+``reboot(b)`` is good when you're unable to shut down, it is an equivalent
-``sync(s)`` and ``umount(u)`` first.
+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
+``sync(s)`` is handy before yanking removable medium or after using a rescue
-disks and will certainly lessen the chance of data loss and fscking. Note
+shell that provides no graceful shutdown -- it will ensure your data is
-that the sync hasn't taken place until you see the "OK" and "Done" appear
+safely written to the disk. Note that the sync hasn't taken place until you see
-on the screen. (If the kernel is really in strife, you may not ever get the
+the "OK" and "Done" appear on the screen.
-OK or Done message...)
 
-``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally
+``umount(u)`` can be used to mark filesystems as properly unmounted. From the
-``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved
+running system's point of view, they will be remounted read-only. The remount
-me many a fsck. Again, the unmount (remount read-only) hasn't taken place until
+isn't complete until you see the "OK" and "Done" message appear on the screen.
-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

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).

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
+	$ cd source/directory
-$ make
+	$ 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
+	$ make install
-$ depmod -a
+	$ 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:
+   It has to be installed in the target system::
-     *
+
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+	$ 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: 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: 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:
+   of different submodules::
-     *
+
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+	# 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_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+	/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_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+	/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_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+	/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_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+	/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
+	$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
+	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:
+   1::
-     *
+
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+	$ 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

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`

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:
+   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
+	# 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

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
 ==============

Documentation/arm/sa1100/adsbitsy.rst

@@ -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!

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
 

Documentation/arm/sa1100/brutus.rst

@@ -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 !

Documentation/arm/sa1100/freebird.rst

@@ -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>

Documentation/arm/sa1100/graphicsclient.rst

@@ -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!

Documentation/arm/sa1100/graphicsmaster.rst

@@ -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!

Documentation/arm/sa1100/huw_webpanel.rst

@@ -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/

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

Documentation/arm/sa1100/itsy.rst

@@ -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.

Documentation/arm/sa1100/nanoengine.rst

@@ -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

Documentation/arm/sa1100/pangolin.rst

@@ -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)

Documentation/arm/sa1100/pleb.rst

@@ -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

Documentation/arm/sa1100/tifon.rst

@@ -1,7 +0,0 @@
-=====
-Tifon
-=====
-
-More info has to come...
-
-Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se>

Documentation/arm/sa1100/yopy.rst

@@ -1,5 +0,0 @@
-====
-Yopy
-====
-
-See http://www.yopydeveloper.org for more.

Documentation/arm/samsung-s3c24xx/index.rst

@@ -1,6 +1,6 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==========================
+==========================
 Samsung S3C24XX SoC Family
 ==========================
 

Documentation/arm/sh-mobile/.gitignore

@@ -1 +0,0 @@
-vrl4

Documentation/auxdisplay/cfag12864b

@@ -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.

Documentation/auxdisplay/ks0108

@@ -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.

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
    =======

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
+  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
-3                       2                       1                        0
+  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
+  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
-3                       2                        1                       0
+  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
+  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
-0                       1                       2                       3
+  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
+  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
-0                       1                       2                       3
+  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
+  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
-7                       6                       5                        4
+  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
+  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
-7                       6                        5                       4
+  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
+  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
-4                       5                       6                       7
+  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
+  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
-4                       5                       6                       7
+  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

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
+		char			%d or %x
-		unsigned char		%hhu or %hhx
+		unsigned char		%u or %x
-		short int		%hd or %hx
+		short int		%d or %x
-		unsigned short int	%hu or %hx
+		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
+		s8			%d or %x
-		u8			%hhu or %hhx
+		u8			%u or %x
-		s16			%hd or %hx
+		s16			%d or %x
-		u16			%hu or %hx
+		u16			%u or %x
 		s32			%d or %x
 		u32			%u or %x
 		s64			%lld or %llx

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.

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

Documentation/devicetree/writing-schema.md

@@ -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/)

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/>`_

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
    =======

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

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.

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

Documentation/driver-api/soundwire/index.rst

@@ -10,7 +10,7 @@ SoundWire Documentation
    error_handling
    locking
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======

Documentation/driver-api/thermal/index.rst

@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =======
 Thermal

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
 

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.

Documentation/features/locking/queued-rwlocks/arch-support.txt

@@ -30,5 +30,5 @@
     |          um: | TODO |
     |   unicore32: | TODO |
     |         x86: |  ok  |
-    |      xtensa: | TODO |
+    |      xtensa: |  ok  |
     -----------------------

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  |
     -----------------------

Documentation/features/locking/rwsem-optimized/arch-support.txt

@@ -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  |
-    -----------------------

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 */
   };

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.

Documentation/filesystems/index.rst

@@ -20,6 +20,10 @@ algorithms work.
    path-lookup
    api-summary
    splice
+   locking
+   directory-locking
+
+   porting
 
 Filesystem support layers
 =========================

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 --------------------------
+Thing currently missing here: socket operations. Alexey?
-prototypes:
+
+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 -----------------------
+xattr_handler operations
-prototypes:
+========================
+
+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 ---------------------------
+file_system_type
-prototypes:
+================
+
+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 --------------------------
+address_space_operations
-prototypes:
+========================
+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_begin:		locks the page		 exclusive
-write_end:		yes, unlocks		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
+``*nr_to_write`` pages.  ``*nr_to_write`` must be decremented for each page
-written.  The address_space implementation may write more (or less) pages
+which is written.  The address_space implementation may write more (or less)
-than *nr_to_write asks for, but it should try to be reasonably close.  If
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
-nr_to_write is NULL, all dirty pages must be written.
+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 ------------------------------
+file_lock_operations
-prototypes:
+====================
+
+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
+.. [1]:
-to block. Leases however can still be freed while the i_lock is held and
+   ->fl_release_private for flock or POSIX locks is currently allowed
-so fl_release_private called on a lease should not block.
+   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 -----------------------
+block_device_operations
-prototypes:
+=======================
+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 -------------------------------
+file_operations
-prototypes:
+===============
+
+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 -------------------------------
+dquot_operations
-prototypes:
+================
+
+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 -----------------------------
+vm_operations_struct
-prototypes:
+====================
+
+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

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.
+   1. provide the filehandle fragment routines described below.
-   2/ make sure that d_splice_alias is used rather than d_add
+   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:

Documentation/filesystems/porting

@@ -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().

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().

Documentation/filesystems/ubifs-authentication.rst

@@ -1,8 +1,11 @@
-% UBIFS Authentication
+:orphan:
-% sigma star gmbh
-% 2018
 
-# 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
+.. [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
+   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
+   written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+   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
 

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)

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.
 

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

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

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

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.
 
 

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.
 
 

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

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.
 
 

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

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

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.
 
 

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

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:

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:
 

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:

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

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.
 
 

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.
 
 

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.
 
 

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.

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::

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>,
+	- Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
+	- Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Dan Eaton <dan.eaton@rocketlogix.com>,
+	- Dan Eaton <dan.eaton@rocketlogix.com>,
-	Stephen Rousset<stephen.rousset@rocketlogix.com>
+	- Stephen Rousset<stephen.rousset@rocketlogix.com>
 
 Description
 -----------

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/
 

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>,
+	- Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
+	- Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.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
+	- Asus P5A
-	Atrend ATC-5220
+	- Atrend ATC-5220
-	BCM/GVC VP1541
+	- BCM/GVC VP1541
-	Biostar M5ALA
+	- Biostar M5ALA
-	Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
+	- Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
-                            enable the 7101 device! **)
+	  enable the 7101 device!)
-	Iwill XA100 Plus
+	- Iwill XA100 Plus
-	Micronics C200
+	- Micronics C200
-	Microstar (MSI) MS-5169
+	- 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 **
+.. important::
-** If you have a M1533 or M1543C on the board and you get
+
-** "ali15x3: Error: Can't detect ali15x3!"
+   If you have a M1533 or M1543C on the board and you get
-** then run lspci.
+   "ali15x3: Error: Can't detect ali15x3!"
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
+   then run lspci.
-** then you must enable ACPI, the PMU, SMB, or something similar
+
-** in the BIOS.
+   If you see the 1533 and 5229 devices but NOT the 7101 device,
-** The driver won't work if it can't find the M7101 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.
-