docs: block: convert to ReST

Rename the block documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Documentation/admin-guide/kernel-parameters.txt

@@ -430,7 +430,7 @@
 
 	blkdevparts=	Manual partition parsing of block device(s) for
 			embedded devices based on command line input.
-			See Documentation/block/cmdline-partition.txt
+			See Documentation/block/cmdline-partition.rst
 
 	boot_delay=	Milliseconds to delay each printk during boot.
 			Values larger than 10 seconds (10000) are changed to
@@ -1199,9 +1199,9 @@
 
 	elevator=	[IOSCHED]
 			Format: { "mq-deadline" | "kyber" | "bfq" }
-			See Documentation/block/deadline-iosched.txt,
-			Documentation/block/kyber-iosched.txt and
-			Documentation/block/bfq-iosched.txt for details.
+			See Documentation/block/deadline-iosched.rst,
+			Documentation/block/kyber-iosched.rst and
+			Documentation/block/bfq-iosched.rst for details.
 
 	elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390]
 			Specifies physical address of start of kernel core

Documentation/block/bfq-iosched.txt → Documentation/block/bfq-iosched.rst

+==========================
 BFQ (Budget Fair Queueing)
 ==========================
 
 BFQ is a proportional-share I/O scheduler, with some extra
 low-latency capabilities. In addition to cgroups support (blkio or io
 controllers), BFQ's main features are:
+
 - BFQ guarantees a high system and application responsiveness, and a
   low latency for time-sensitive applications, such as audio or video
   players;
@@ -55,18 +57,18 @@ sustainable throughputs, on the same systems as above:
 
 BFQ works for multi-queue devices too.
 
-The table of contents follow. Impatients can just jump to Section 3.
+.. The table of contents follow. Impatients can just jump to Section 3.
 
-CONTENTS
+.. CONTENTS
 
-1. When may BFQ be useful?
- 1-1 Personal systems
- 1-2 Server systems
-2. How does BFQ work?
-3. What are BFQ's tunables and how to properly configure BFQ?
-4. BFQ group scheduling
- 4-1 Service guarantees provided
- 4-2 Interface
+   1. When may BFQ be useful?
+    1-1 Personal systems
+    1-2 Server systems
+   2. How does BFQ work?
+   3. What are BFQ's tunables and how to properly configure BFQ?
+   4. BFQ group scheduling
+    4-1 Service guarantees provided
+    4-2 Interface
 
 1. When may BFQ be useful?
 ==========================
@@ -77,17 +79,20 @@ BFQ provides the following benefits on personal and server systems.
 --------------------
 
 Low latency for interactive applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Regardless of the actual background workload, BFQ guarantees that, for
 interactive tasks, the storage device is virtually as responsive as if
 it was idle. For example, even if one or more of the following
 background workloads are being executed:
+
 - one or more large files are being read, written or copied,
 - a tree of source files is being compiled,
 - one or more virtual machines are performing I/O,
 - a software update is in progress,
 - indexing daemons are scanning filesystems and updating their
   databases,
+
 starting an application or loading a file from within an application
 takes about the same time as if the storage device was idle. As a
 comparison, with CFQ, NOOP or DEADLINE, and in the same conditions,
@@ -95,13 +100,14 @@ applications experience high latencies, or even become unresponsive
 until the background workload terminates (also on SSDs).
 
 Low latency for soft real-time applications
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Also soft real-time applications, such as audio and video
 players/streamers, enjoy a low latency and a low drop rate, regardless
 of the background I/O workload. As a consequence, these applications
 do not suffer from almost any glitch due to the background workload.
 
 Higher speed for code-development tasks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If some additional workload happens to be executed in parallel, then
 BFQ executes the I/O-related components of typical code-development
@@ -109,6 +115,7 @@ tasks (compilation, checkout, merge, ...) much more quickly than CFQ,
 NOOP or DEADLINE.
 
 High throughput
+^^^^^^^^^^^^^^^
 
 On hard disks, BFQ achieves up to 30% higher throughput than CFQ, and
 up to 150% higher throughput than DEADLINE and NOOP, with all the
@@ -117,6 +124,7 @@ and with all the workloads on flash-based devices, BFQ achieves,
 instead, about the same throughput as the other schedulers.
 
 Strong fairness, bandwidth and delay guarantees
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 BFQ distributes the device throughput, and not just the device time,
 among I/O-bound applications in proportion their weights, with any
@@ -133,15 +141,15 @@ Most benefits for server systems follow from the same service
 properties as above. In particular, regardless of whether additional,
 possibly heavy workloads are being served, BFQ guarantees:
 
-. audio and video-streaming with zero or very low jitter and drop
+* audio and video-streaming with zero or very low jitter and drop
   rate;
 
-. fast retrieval of WEB pages and embedded objects;
+* fast retrieval of WEB pages and embedded objects;
 
-. real-time recording of data in live-dumping applications (e.g.,
+* real-time recording of data in live-dumping applications (e.g.,
   packet logging);
 
-. responsiveness in local and remote access to a server.
+* responsiveness in local and remote access to a server.
 
 
 2. How does BFQ work?
@@ -151,7 +159,7 @@ BFQ is a proportional-share I/O scheduler, whose general structure,
 plus a lot of code, are borrowed from CFQ.
 
 - Each process doing I/O on a device is associated with a weight and a
-  (bfq_)queue.
+  `(bfq_)queue`.
 
 - BFQ grants exclusive access to the device, for a while, to one queue
   (process) at a time, and implements this service model by
@@ -540,11 +548,12 @@ created, and kept up-to-date by bfq, depends on whether
 CONFIG_BFQ_CGROUP_DEBUG is set. If it is set, then bfq creates all
 the stat files documented in
 Documentation/cgroup-v1/blkio-controller.rst. If, instead,
-CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files
-blkio.bfq.io_service_bytes
-blkio.bfq.io_service_bytes_recursive
-blkio.bfq.io_serviced
-blkio.bfq.io_serviced_recursive
+CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files::
+
+  blkio.bfq.io_service_bytes
+  blkio.bfq.io_service_bytes_recursive
+  blkio.bfq.io_serviced
+  blkio.bfq.io_serviced_recursive
 
 The value of CONFIG_BFQ_CGROUP_DEBUG greatly influences the maximum
 throughput sustainable with bfq, because updating the blkio.bfq.*
@@ -567,17 +576,22 @@ weight of the queues associated with interactive and soft real-time
 applications. Unset this tunable if you need/want to control weights.
 
 
-[1] P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O
+[1]
+    P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O
     Scheduler", Proceedings of the First Workshop on Mobile System
     Technologies (MST-2015), May 2015.
+
     http://algogroup.unimore.it/people/paolo/disk_sched/mst-2015.pdf
 
-[2] P. Valente and M. Andreolini, "Improving Application
+[2]
+    P. Valente and M. Andreolini, "Improving Application
     Responsiveness with the BFQ Disk I/O Scheduler", Proceedings of
     the 5th Annual International Systems and Storage Conference
     (SYSTOR '12), June 2012.
+
     Slightly extended version:
-    http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-
-							results.pdf
 
-[3] https://github.com/Algodev-github/S
+    http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-results.pdf
+
+[3]
+   https://github.com/Algodev-github/S

Documentation/block/biovecs.txt → Documentation/block/biovecs.rst

-
-Immutable biovecs and biovec iterators:
-=======================================
+======================================
+Immutable biovecs and biovec iterators
+======================================
 
 Kent Overstreet <kmo@daterainc.com>
 
@@ -121,10 +121,12 @@ Other implications:
 Usage of helpers:
 =================
 
-* The following helpers whose names have the suffix of "_all" can only be used
-on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
-shouldn't use them because the bio may have been split before it reached the
-driver.
+* The following helpers whose names have the suffix of `_all` can only be used
+  on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers
+  shouldn't use them because the bio may have been split before it reached the
+  driver.
+
+::
 
 	bio_for_each_segment_all()
 	bio_first_bvec_all()
@@ -132,13 +134,13 @@ driver.
 	bio_last_bvec_all()
 
 * The following helpers iterate over single-page segment. The passed 'struct
-bio_vec' will contain a single-page IO vector during the iteration
+  bio_vec' will contain a single-page IO vector during the iteration::
 
 	bio_for_each_segment()
 	bio_for_each_segment_all()
 
 * The following helpers iterate over multi-page bvec. The passed 'struct
-bio_vec' will contain a multi-page IO vector during the iteration
+  bio_vec' will contain a multi-page IO vector during the iteration::
 
 	bio_for_each_bvec()
 	rq_for_each_bvec()

Documentation/block/capability.txt → Documentation/block/capability.rst

+===============================
 Generic Block Device Capability
-===============================================================================
+===============================
+
 This file documents the sysfs file block/<disk>/capability
 
 capability is a hex word indicating which capabilities a specific disk
 supports.  For more information on bits not listed here, see
 include/linux/genhd.h
 
-Capability				Value
--------------------------------------------------------------------------------
-GENHD_FL_MEDIA_CHANGE_NOTIFY		4
-	When this bit is set, the disk supports Asynchronous Notification
-	of media change events.  These events will be broadcast to user
-	space via kernel uevent.
+GENHD_FL_MEDIA_CHANGE_NOTIFY
+----------------------------
+
+Value: 4
 
+When this bit is set, the disk supports Asynchronous Notification
+of media change events.  These events will be broadcast to user
+space via kernel uevent.

Documentation/block/cmdline-partition.txt → Documentation/block/cmdline-partition.rst

+==============================================
 Embedded device command line partition parsing
-=====================================================================
+==============================================
 
 The "blkdevparts" command line option adds support for reading the
 block device partition table from the kernel command line.
@@ -22,12 +23,15 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
 <size>
     partition size, in bytes, such as: 512, 1m, 1G.
     size may contain an optional suffix of (upper or lower case):
+
       K, M, G, T, P, E.
+
     "-" is used to denote all remaining space.
 
 <offset>
     partition start address, in bytes.
     offset may contain an optional suffix of (upper or lower case):
+
       K, M, G, T, P, E.
 
 (part-name)
@@ -36,11 +40,14 @@ blkdevparts=<blkdev-def>[;<blkdev-def>]
     User space application can access partition by partition name.
 
 Example:
+
     eMMC disk names are "mmcblk0" and "mmcblk0boot0".
 
-  bootargs:
+  bootargs::
+
     'blkdevparts=mmcblk0:1G(data0),1G(data1),-;mmcblk0boot0:1m(boot),-(kernel)'
 
-  dmesg:
+  dmesg::
+
     mmcblk0: p1(data0) p2(data1) p3()
     mmcblk0boot0: p1(boot) p2(kernel)

Documentation/block/data-integrity.txt → Documentation/block/data-integrity.rst

-----------------------------------------------------------------------
-1. INTRODUCTION
+==============
+Data Integrity
+==============
+
+1. Introduction
+===============
 
 Modern filesystems feature checksumming of data and metadata to
 protect against data corruption.  However, the detection of the
@@ -28,8 +32,8 @@ integrity of the I/O and reject it if corruption is detected.  This
 allows not only corruption prevention but also isolation of the point
 of failure.
 
-----------------------------------------------------------------------
-2. THE DATA INTEGRITY EXTENSIONS
+2. The Data Integrity Extensions
+================================
 
 As written, the protocol extensions only protect the path between
 controller and storage device.  However, many controllers actually
@@ -75,8 +79,8 @@ Extensions.  As these extensions are outside the scope of the protocol
 bodies (T10, T13), Oracle and its partners are trying to standardize
 them within the Storage Networking Industry Association.
 
-----------------------------------------------------------------------
-3. KERNEL CHANGES
+3. Kernel Changes
+=================
 
 The data integrity framework in Linux enables protection information
 to be pinned to I/Os and sent to/received from controllers that
@@ -123,10 +127,11 @@ access to manipulate the tags from user space.  A passthrough
 interface for this is being worked on.
 
 
-----------------------------------------------------------------------
-4. BLOCK LAYER IMPLEMENTATION DETAILS
+4. Block Layer Implementation Details
+=====================================
 
-4.1 BIO
+4.1 Bio
+-------
 
 The data integrity patches add a new field to struct bio when
 CONFIG_BLK_DEV_INTEGRITY is enabled.  bio_integrity(bio) returns a
@@ -145,7 +150,8 @@ attached using bio_integrity_add_page().
 bio_free() will automatically free the bip.
 
 
-4.2 BLOCK DEVICE
+4.2 Block Device
+----------------
 
 Because the format of the protection data is tied to the physical
 disk, each block device has been extended with a block integrity
@@ -163,10 +169,11 @@ and MD linear, RAID0 and RAID1 are currently supported.  RAID4/5/6
 will require extra work due to the application tag.
 
 
-----------------------------------------------------------------------
-5.0 BLOCK LAYER INTEGRITY API
+5.0 Block Layer Integrity API
+=============================
 
-5.1 NORMAL FILESYSTEM
+5.1 Normal Filesystem
+---------------------
 
     The normal filesystem is unaware that the underlying block device
     is capable of sending/receiving integrity metadata.  The IMD will
@@ -174,25 +181,26 @@ will require extra work due to the application tag.
     in case of a WRITE.  A READ request will cause the I/O integrity
     to be verified upon completion.
 
-    IMD generation and verification can be toggled using the
+    IMD generation and verification can be toggled using the::
 
       /sys/block/<bdev>/integrity/write_generate
 
-    and
+    and::
 
       /sys/block/<bdev>/integrity/read_verify
 
     flags.
 
 
-5.2 INTEGRITY-AWARE FILESYSTEM
+5.2 Integrity-Aware Filesystem
+------------------------------
 
     A filesystem that is integrity-aware can prepare I/Os with IMD
     attached.  It can also use the application tag space if this is
     supported by the block device.
 
 
-    bool bio_integrity_prep(bio);
+    `bool bio_integrity_prep(bio);`
 
       To generate IMD for WRITE and to set up buffers for READ, the
       filesystem must call bio_integrity_prep(bio).
@@ -204,14 +212,15 @@ will require extra work due to the application tag.
       Complete bio with error if prepare failed for some reson.
 
 
-5.3 PASSING EXISTING INTEGRITY METADATA
+5.3 Passing Existing Integrity Metadata
+---------------------------------------
 
     Filesystems that either generate their own integrity metadata or
     are capable of transferring IMD from user space can use the
     following calls:
 
 
-    struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);
+    `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
 
       Allocates the bio integrity payload and hangs it off of the bio.
       nr_pages indicate how many pages of protection data need to be
@@ -220,7 +229,7 @@ will require extra work due to the application tag.
       The integrity payload will be freed at bio_free() time.
 
 
-    int bio_integrity_add_page(bio, page, len, offset);
+    `int bio_integrity_add_page(bio, page, len, offset);`
 
       Attaches a page containing integrity metadata to an existing
       bio.  The bio must have an existing bip,
@@ -241,21 +250,21 @@ will require extra work due to the application tag.
       integrity upon completion.
 
 
-5.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY
-    METADATA
+5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata
+--------------------------------------------------------------------------
 
     To enable integrity exchange on a block device the gendisk must be
     registered as capable:
 
-    int blk_integrity_register(gendisk, blk_integrity);
+    `int blk_integrity_register(gendisk, blk_integrity);`
 
       The blk_integrity struct is a template and should contain the
-      following:
+      following::
 
         static struct blk_integrity my_profile = {
             .name                   = "STANDARDSBODY-TYPE-VARIANT-CSUM",
             .generate_fn            = my_generate_fn,
-       	    .verify_fn              = my_verify_fn,
+	    .verify_fn              = my_verify_fn,
 	    .tuple_size             = sizeof(struct my_tuple_size),
 	    .tag_size               = <tag bytes per hw sector>,
         };
@@ -278,4 +287,5 @@ will require extra work due to the application tag.
       0 depending on the value of the Control Mode Page ATO bit.
 
 ----------------------------------------------------------------------
+
 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>

Documentation/block/deadline-iosched.txt → Documentation/block/deadline-iosched.rst

+==============================
 Deadline IO scheduler tunables
 ==============================
 
@@ -7,15 +8,13 @@ of interest to power users.
 
 Selecting IO schedulers
 -----------------------
-Refer to Documentation/block/switching-sched.txt for information on
+Refer to Documentation/block/switching-sched.rst for information on
 selecting an io scheduler on a per-device basis.
 
-
-********************************************************************************
-
+------------------------------------------------------------------------------
 
 read_expire	(in ms)
------------
+-----------------------
 
 The goal of the deadline io scheduler is to attempt to guarantee a start
 service time for a request. As we focus mainly on read latencies, this is
@@ -25,15 +24,15 @@ milliseconds.
 
 
 write_expire	(in ms)
------------
+-----------------------
 
 Similar to read_expire mentioned above, but for writes.
 
 
 fifo_batch	(number of requests)
-----------
+------------------------------------
 
-Requests are grouped into ``batches'' of a particular data direction (read or
+Requests are grouped into ``batches`` of a particular data direction (read or
 write) which are serviced in increasing sector order.  To limit extra seeking,
 deadline expiries are only checked between batches.  fifo_batch controls the
 maximum number of requests per batch.
@@ -45,7 +44,7 @@ generally improves throughput, at the cost of latency variation.
 
 
 writes_starved	(number of dispatches)
---------------
+--------------------------------------
 
 When we have to move requests from the io scheduler queue to the block
 device dispatch queue, we always give a preference to reads. However, we
@@ -56,7 +55,7 @@ same criteria as reads.
 
 
 front_merges	(bool)
-------------
+----------------------
 
 Sometimes it happens that a request enters the io scheduler that is contiguous
 with a request that is already on the queue. Either it fits in the back of that
@@ -71,5 +70,3 @@ rbtree front sector lookup when the io scheduler merge function is called.
 
 
 Nov 11 2002, Jens Axboe <jens.axboe@oracle.com>
-
-

Documentation/block/index.rst

+:orphan:
+
+=====
+Block
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   bfq-iosched
+   biodoc
+   biovecs
+   capability
+   cmdline-partition
+   data-integrity
+   deadline-iosched
+   ioprio
+   kyber-iosched
+   null_blk
+   pr
+   queue-sysfs
+   request
+   stat
+   switching-sched
+   writeback_cache_control

Documentation/block/ioprio.txt → Documentation/block/ioprio.rst

+===================
 Block io priorities
 ===================
 
@@ -40,81 +41,81 @@ class data, since it doesn't really apply here.
 Tools
 -----
 
-See below for a sample ionice tool. Usage:
+See below for a sample ionice tool. Usage::
 
-# ionice -c<class> -n<level> -p<pid>
+	# ionice -c<class> -n<level> -p<pid>
 
 If pid isn't given, the current process is assumed. IO priority settings
 are inherited on fork, so you can use ionice to start the process at a given
-level:
+level::
 
-# ionice -c2 -n0 /bin/ls
+	# ionice -c2 -n0 /bin/ls
 
 will run ls at the best-effort scheduling class at the highest priority.
-For a running process, you can give the pid instead:
+For a running process, you can give the pid instead::
 
-# ionice -c1 -n2 -p100
+	# ionice -c1 -n2 -p100
 
 will change pid 100 to run at the realtime scheduling class, at priority 2.
 
----> snip ionice.c tool <---
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <getopt.h>
-#include <unistd.h>
-#include <sys/ptrace.h>
-#include <asm/unistd.h>
-
-extern int sys_ioprio_set(int, int, int);
-extern int sys_ioprio_get(int, int);
-
-#if defined(__i386__)
-#define __NR_ioprio_set		289
-#define __NR_ioprio_get		290
-#elif defined(__ppc__)
-#define __NR_ioprio_set		273
-#define __NR_ioprio_get		274
-#elif defined(__x86_64__)
-#define __NR_ioprio_set		251
-#define __NR_ioprio_get		252
-#elif defined(__ia64__)
-#define __NR_ioprio_set		1274
-#define __NR_ioprio_get		1275
-#else
-#error "Unsupported arch"
-#endif
-
-static inline int ioprio_set(int which, int who, int ioprio)
-{
+ionice.c tool::
+
+  #include <stdio.h>
+  #include <stdlib.h>
+  #include <errno.h>
+  #include <getopt.h>
+  #include <unistd.h>
+  #include <sys/ptrace.h>
+  #include <asm/unistd.h>
+
+  extern int sys_ioprio_set(int, int, int);
+  extern int sys_ioprio_get(int, int);
+
+  #if defined(__i386__)
+  #define __NR_ioprio_set		289
+  #define __NR_ioprio_get		290
+  #elif defined(__ppc__)
+  #define __NR_ioprio_set		273
+  #define __NR_ioprio_get		274
+  #elif defined(__x86_64__)
+  #define __NR_ioprio_set		251
+  #define __NR_ioprio_get		252
+  #elif defined(__ia64__)
+  #define __NR_ioprio_set		1274
+  #define __NR_ioprio_get		1275
+  #else
+  #error "Unsupported arch"
+  #endif
+
+  static inline int ioprio_set(int which, int who, int ioprio)
+  {
 	return syscall(__NR_ioprio_set, which, who, ioprio);
-}
+  }
 
-static inline int ioprio_get(int which, int who)
-{
+  static inline int ioprio_get(int which, int who)
+  {
 	return syscall(__NR_ioprio_get, which, who);
-}
+  }
 
-enum {
+  enum {
 	IOPRIO_CLASS_NONE,
 	IOPRIO_CLASS_RT,
 	IOPRIO_CLASS_BE,
 	IOPRIO_CLASS_IDLE,
-};
+  };
 
-enum {
+  enum {
 	IOPRIO_WHO_PROCESS = 1,
 	IOPRIO_WHO_PGRP,
 	IOPRIO_WHO_USER,
-};
+  };
 
-#define IOPRIO_CLASS_SHIFT	13
+  #define IOPRIO_CLASS_SHIFT	13
 
-const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
+  const char *to_prio[] = { "none", "realtime", "best-effort", "idle", };
 
-int main(int argc, char *argv[])
-{
+  int main(int argc, char *argv[])
+  {
 	int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE;
 	int c, pid = 0;
 
@@ -175,9 +176,7 @@ int main(int argc, char *argv[])
 	}
 
 	return 0;
-}
-
----> snip ionice.c tool <---
+  }
 
 
 March 11 2005, Jens Axboe <jens.axboe@oracle.com>

Documentation/block/kyber-iosched.txt → Documentation/block/kyber-iosched.rst

+============================
 Kyber I/O scheduler tunables
-===========================
+============================
 
 The only two tunables for the Kyber scheduler are the target latencies for
 reads and synchronous writes. Kyber will throttle requests in order to meet

Documentation/block/null_blk.txt → Documentation/block/null_blk.rst

+========================
 Null block device driver
-================================================================================
+========================
 
-I. Overview
+1. Overview
+===========
 
 The null block device (/dev/nullb*) is used for benchmarking the various
 block-layer implementations. It emulates a block device of X gigabytes in size.
 The following instances are possible:
 
   Single-queue block-layer
+
     - Request-based.
     - Single submission queue per device.
     - Implements IO scheduling algorithms (CFQ, Deadline, noop).
+
   Multi-queue block-layer
+
     - Request-based.
     - Configurable submission queues per device.
+
   No block-layer (Known as bio-based)
+
     - Bio-based. IO requests are submitted directly to the device driver.
     - Directly accepts bio data structure and returns them.
 
 All of them have a completion queue for each core in the system.
 
-II. Module parameters applicable for all instances:
+2. Module parameters applicable for all instances
+=================================================
 
 queue_mode=[0-2]: Default: 2-Multi-queue
   Selects which block-layer the module should instantiate with.
 
-  0: Bio-based.
-  1: Single-queue.
-  2: Multi-queue.
+  =  ============
+  0  Bio-based
+  1  Single-queue
+  2  Multi-queue
+  =  ============
 
 home_node=[0--nr_nodes]: Default: NUMA_NO_NODE
   Selects what CPU node the data structures are allocated from.
@@ -45,12 +55,14 @@ nr_devices=[Number of devices]: Default: 1
 irqmode=[0-2]: Default: 1-Soft-irq
   The completion mode used for completing IOs to the block-layer.
 
-  0: None.
-  1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
+  =  ===========================================================================
+  0  None.
+  1  Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead
      when IOs are issued from another CPU node than the home the device is
      connected to.
-  2: Timer: Waits a specific period (completion_nsec) for each IO before
+  2  Timer: Waits a specific period (completion_nsec) for each IO before
      completion.
+  =  ===========================================================================
 
 completion_nsec=[ns]: Default: 10,000ns
   Combined with irqmode=2 (timer). The time each completion event must wait.
@@ -66,30 +78,45 @@ hw_queue_depth=[0..qdepth]: Default: 64
 III: Multi-queue specific parameters
 
 use_per_node_hctx=[0/1]: Default: 0
-  0: The number of submit queues are set to the value of the submit_queues
+
+  =  =====================================================================
+  0  The number of submit queues are set to the value of the submit_queues
      parameter.
-  1: The multi-queue block layer is instantiated with a hardware dispatch
+  1  The multi-queue block layer is instantiated with a hardware dispatch
      queue for each CPU node in the system.
+  =  =====================================================================
 
 no_sched=[0/1]: Default: 0
-  0: nullb* use default blk-mq io scheduler.
-  1: nullb* doesn't use io scheduler.
+
+  =  ======================================
+  0  nullb* use default blk-mq io scheduler
+  1  nullb* doesn't use io scheduler
+  =  ======================================
 
 blocking=[0/1]: Default: 0
-  0: Register as a non-blocking blk-mq driver device.
-  1: Register as a blocking blk-mq driver device, null_blk will set
+
+  =  ===============================================================
+  0  Register as a non-blocking blk-mq driver device.
+  1  Register as a blocking blk-mq driver device, null_blk will set
      the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always
      needs to block in its ->queue_rq() function.
+  =  ===============================================================
 
 shared_tags=[0/1]: Default: 0
-  0: Tag set is not shared.
-  1: Tag set shared between devices for blk-mq. Only makes sense with
+
+  =  ================================================================
+  0  Tag set is not shared.
+  1  Tag set shared between devices for blk-mq. Only makes sense with
      nr_devices > 1, otherwise there's no tag set to share.
+  =  ================================================================
 
 zoned=[0/1]: Default: 0
-  0: Block device is exposed as a random-access block device.
-  1: Block device is exposed as a host-managed zoned block device. Requires
+
+  =  ======================================================================
+  0  Block device is exposed as a random-access block device.
+  1  Block device is exposed as a host-managed zoned block device. Requires
      CONFIG_BLK_DEV_ZONED.
+  =  ======================================================================
 
 zone_size=[MB]: Default: 256
   Per zone size when exposed as a zoned block device. Must be a power of two.

Documentation/block/pr.txt → Documentation/block/pr.rst

-
+===============================================
 Block layer support for Persistent Reservations
 ===============================================
 
@@ -23,22 +23,18 @@ The following types of reservations are supported:
 --------------------------------------------------
 
  - PR_WRITE_EXCLUSIVE
-
 	Only the initiator that owns the reservation can write to the
 	device.  Any initiator can read from the device.
 
  - PR_EXCLUSIVE_ACCESS
-
 	Only the initiator that owns the reservation can access the
 	device.
 
  - PR_WRITE_EXCLUSIVE_REG_ONLY
-
 	Only initiators with a registered key can write to the device,
 	Any initiator can read from the device.
 
  - PR_EXCLUSIVE_ACCESS_REG_ONLY
-
 	Only initiators with a registered key can access the device.
 
  - PR_WRITE_EXCLUSIVE_ALL_REGS
@@ -48,21 +44,21 @@ The following types of reservations are supported:
 	All initiators with a registered key are considered reservation
 	holders.
 	Please reference the SPC spec on the meaning of a reservation
-	holder if you want to use this type. 
+	holder if you want to use this type.
 
  - PR_EXCLUSIVE_ACCESS_ALL_REGS
-
 	Only initiators with a registered key can access the device.
 	All initiators with a registered key are considered reservation
 	holders.
 	Please reference the SPC spec on the meaning of a reservation
-	holder if you want to use this type. 
+	holder if you want to use this type.
 
 
 The following ioctl are supported:
 ----------------------------------
 
 1. IOC_PR_REGISTER
+^^^^^^^^^^^^^^^^^^
 
 This ioctl command registers a new reservation if the new_key argument
 is non-null.  If no existing reservation exists old_key must be zero,
@@ -74,6 +70,7 @@ in old_key.
 
 
 2. IOC_PR_RESERVE
+^^^^^^^^^^^^^^^^^
 
 This ioctl command reserves the device and thus restricts access for other
 devices based on the type argument.  The key argument must be the existing
@@ -82,12 +79,14 @@ IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.
 
 
 3. IOC_PR_RELEASE
+^^^^^^^^^^^^^^^^^
 
 This ioctl command releases the reservation specified by key and flags
 and thus removes any access restriction implied by it.
 
 
 4. IOC_PR_PREEMPT
+^^^^^^^^^^^^^^^^^
 
 This ioctl command releases the existing reservation referred to by
 old_key and replaces it with a new reservation of type for the
@@ -95,11 +94,13 @@ reservation key new_key.
 
 
 5. IOC_PR_PREEMPT_ABORT
+^^^^^^^^^^^^^^^^^^^^^^^
 
 This ioctl command works like IOC_PR_PREEMPT except that it also aborts
 any outstanding command sent over a connection identified by old_key.
 
 6. IOC_PR_CLEAR
+^^^^^^^^^^^^^^^
 
 This ioctl command unregisters both key and any other reservation key
 registered with the device and drops any existing reservation.
@@ -111,7 +112,6 @@ Flags
 All the ioctls have a flag field.  Currently only one flag is supported:
 
  - PR_FL_IGNORE_KEY
-
 	Ignore the existing reservation key.  This is commonly supported for
 	IOC_PR_REGISTER, and some implementation may support the flag for
 	IOC_PR_RESERVE.

Documentation/block/queue-sysfs.txt → Documentation/block/queue-sysfs.rst

+=================
 Queue sysfs files
 =================
 
@@ -10,7 +11,7 @@ Files denoted with a RO postfix are readonly and the RW postfix means
 read-write.
 
 add_random (RW)
-----------------
+---------------
 This file allows to turn off the disk entropy contribution. Default
 value of this file is '1'(on).
 
@@ -30,13 +31,13 @@ used by CPU-addressable storage to bypass the pagecache.  It shows '1'
 if true, '0' if not.
 
 discard_granularity (RO)
------------------------
+------------------------
 This shows the size of internal allocation of the device in bytes, if
 reported by the device. A value of '0' means device does not support
 the discard functionality.
 
 discard_max_hw_bytes (RO)
-----------------------
+-------------------------
 Devices that support discard functionality may have internal limits on
 the number of bytes that can be trimmed or unmapped in a single operation.
 The discard_max_bytes parameter is set by the device driver to the maximum

Documentation/block/request.txt → Documentation/block/request.rst

-
+============================
 struct request documentation
+============================
 
 Jens Axboe <jens.axboe@oracle.com> 27/05/02
 
-1.0
-Index
 
-2.0 Struct request members classification
+.. FIXME:
+   No idea about what does mean - seems just some noise, so comment it
+
+   1.0
+   Index
+
+   2.0 Struct request members classification
+
+       2.1 struct request members explanation
 
-	2.1 struct request members explanation
+   3.0
+
+
+   2.0
 
-3.0
 
 
-2.0
 Short explanation of request members
+====================================
 
 Classification flags:
 
+	=	====================
 	D	driver member
 	B	block layer member
 	I	I/O scheduler member
+	=	====================
 
 Unless an entry contains a D classification, a device driver must not access
 this member. Some members may contain D classifications, but should only be
@@ -28,14 +39,13 @@ access through certain macros or functions (eg ->flags).
 
 <linux/blkdev.h>
 
-2.1
+=============================== ======= =======================================
 Member				Flag	Comment
-------				----	-------
-
+=============================== ======= =======================================
 struct list_head queuelist	BI	Organization on various internal
 					queues
 
-void *elevator_private		I	I/O scheduler private data
+``void *elevator_private``	I	I/O scheduler private data
 
 unsigned char cmd[16]		D	Driver can use this for setting up
 					a cdb before execution, see
@@ -71,18 +81,19 @@ unsigned int hard_cur_sectors	B	Used to keep current_nr_sectors sane
 
 int tag				DB	TCQ tag, if assigned
 
-void *special			D	Free to be used by driver
+``void *special``		D	Free to be used by driver
 
-char *buffer			D	Map of first segment, also see
+``char *buffer``		D	Map of first segment, also see
 					section on bouncing SECTION
 
-struct completion *waiting	D	Can be used by driver to get signalled
+``struct completion *waiting``	D	Can be used by driver to get signalled
 					on request completion
 
-struct bio *bio			DBI	First bio in request
+``struct bio *bio``		DBI	First bio in request
 
-struct bio *biotail		DBI	Last bio in request
+``struct bio *biotail``		DBI	Last bio in request
 
-struct request_queue *q		DB	Request queue this request belongs to
+``struct request_queue *q``	DB	Request queue this request belongs to
 
-struct request_list *rl		B	Request list this request came from
+``struct request_list *rl``	B	Request list this request came from
+=============================== ======= =======================================

Documentation/block/stat.txt → Documentation/block/stat.rst

+===============================================
 Block layer statistics in /sys/block/<dev>/stat
 ===============================================
 
@@ -6,9 +7,12 @@ This file documents the contents of the /sys/block/<dev>/stat file.
 The stat file provides several statistics about the state of block
 device <dev>.
 
-Q. Why are there multiple statistics in a single file?  Doesn't sysfs
+Q.
+   Why are there multiple statistics in a single file?  Doesn't sysfs
    normally contain a single value per file?
-A. By having a single file, the kernel can guarantee that the statistics
+
+A.
+   By having a single file, the kernel can guarantee that the statistics
    represent a consistent snapshot of the state of the device.  If the
    statistics were exported as multiple files containing one statistic
    each, it would be impossible to guarantee that a set of readings
@@ -18,8 +22,10 @@ The stat file consists of a single line of text containing 11 decimal
 values separated by whitespace.  The fields are summarized in the
 following table, and described in more detail below.
 
+
+=============== ============= =================================================
 Name            units         description
-----            -----         -----------
+=============== ============= =================================================
 read I/Os       requests      number of read I/Os processed
 read merges     requests      number of read I/Os merged with in-queue I/O
 read sectors    sectors       number of sectors read
@@ -35,6 +41,7 @@ discard I/Os    requests      number of discard I/Os processed
 discard merges  requests      number of discard I/Os merged with in-queue I/O
 discard sectors sectors       number of sectors discarded
 discard ticks   milliseconds  total wait time for discard requests
+=============== ============= =================================================
 
 read I/Os, write I/Os, discard I/0s
 ===================================

Documentation/block/switching-sched.txt → Documentation/block/switching-sched.rst

+===================
+Switching Scheduler
+===================
+
 To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
 'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
 globally at boot time only presently.
 
 Each io queue has a set of io scheduler tunables associated with it. These
 tunables control how the io scheduler works. You can find these entries
-in:
+in::
 
-/sys/block/<device>/queue/iosched
+	/sys/block/<device>/queue/iosched
 
 assuming that you have sysfs mounted on /sys. If you don't have sysfs mounted,
-you can do so by typing:
+you can do so by typing::
 
-# mount none /sys -t sysfs
+	# mount none /sys -t sysfs
 
 It is possible to change the IO scheduler for a given block device on
 the fly to select one of mq-deadline, none, bfq, or kyber schedulers -
 which can improve that device's throughput.
 
-To set a specific scheduler, simply do this:
+To set a specific scheduler, simply do this::
 
-echo SCHEDNAME > /sys/block/DEV/queue/scheduler
+	echo SCHEDNAME > /sys/block/DEV/queue/scheduler
 
 where SCHEDNAME is the name of a defined IO scheduler, and DEV is the
 device name (hda, hdb, sga, or whatever you happen to have).
 
 The list of defined schedulers can be found by simply doing
 a "cat /sys/block/DEV/queue/scheduler" - the list of valid names
-will be displayed, with the currently selected scheduler in brackets:
+will be displayed, with the currently selected scheduler in brackets::
 
-# cat /sys/block/sda/queue/scheduler
-[mq-deadline] kyber bfq none
-# echo none >/sys/block/sda/queue/scheduler
-# cat /sys/block/sda/queue/scheduler
-[none] mq-deadline kyber bfq
+  # cat /sys/block/sda/queue/scheduler
+  [mq-deadline] kyber bfq none
+  # echo none >/sys/block/sda/queue/scheduler
+  # cat /sys/block/sda/queue/scheduler
+  [none] mq-deadline kyber bfq

Documentation/block/writeback_cache_control.txt → Documentation/block/writeback_cache_control.rst

-
+==========================================
 Explicit volatile write back cache control
-=====================================
+==========================================
 
 Introduction
 ------------
@@ -31,7 +31,7 @@ the blkdev_issue_flush() helper for a pure cache flush.
 
 
 Forced Unit Access
------------------
+------------------
 
 The REQ_FUA flag can be OR ed into the r/w flags of a bio submitted from the
 filesystem and will make sure that I/O completion for this request is only
@@ -62,14 +62,14 @@ flags themselves without any help from the block layer.
 
 
 Implementation details for request_fn based block drivers
---------------------------------------------------------------
+---------------------------------------------------------
 
 For devices that do not support volatile write caches there is no driver
 support required, the block layer completes empty REQ_PREFLUSH requests before
 entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from
 requests that have a payload.  For devices with volatile write caches the
 driver needs to tell the block layer that it supports flushing caches by
-doing:
+doing::
 
 	blk_queue_write_cache(sdkp->disk->queue, true, false);
 
@@ -77,7 +77,7 @@ and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn.  Note that
 REQ_PREFLUSH requests with a payload are automatically turned into a sequence
 of an empty REQ_OP_FLUSH request followed by the actual write by the block
 layer.  For devices that also support the FUA bit the block layer needs
-to be told to pass through the REQ_FUA bit using:
+to be told to pass through the REQ_FUA bit using::
 
 	blk_queue_write_cache(sdkp->disk->queue, true, true);
 

Documentation/blockdev/zram.rst

@@ -215,7 +215,7 @@ User space is advised to use the following files to read the device statistics.
 
 File /sys/block/zram<id>/stat
 
-Represents block layer statistics. Read Documentation/block/stat.txt for
+Represents block layer statistics. Read Documentation/block/stat.rst for
 details.
 
 File /sys/block/zram<id>/io_stat

MAINTAINERS

@@ -2968,7 +2968,7 @@ M:	Jens Axboe <axboe@kernel.dk>
 L:	linux-block@vger.kernel.org
 S:	Maintained
 F:	block/bfq-*
-F:	Documentation/block/bfq-iosched.txt
+F:	Documentation/block/bfq-iosched.rst
 
 BFS FILE SYSTEM
 M:	"Tigran A. Aivazian" <aivazian.tigran@gmail.com>

block/Kconfig

@@ -110,7 +110,7 @@ config BLK_CMDLINE_PARSER
 	which don't otherwise have any standardized method for listing the
 	partitions on a block device.
 
-	See Documentation/block/cmdline-partition.txt for more information.
+	See Documentation/block/cmdline-partition.rst for more information.
 
 config BLK_WBT
 	bool "Enable support for block device writeback throttling"

block/Kconfig.iosched

@@ -26,7 +26,7 @@ config IOSCHED_BFQ
 	regardless of the device parameters and with any workload. It
 	also guarantees a low latency to interactive and soft
 	real-time applications.  Details in
-	Documentation/block/bfq-iosched.txt
+	Documentation/block/bfq-iosched.rst
 
 config BFQ_GROUP_IOSCHED
        bool "BFQ hierarchical scheduling support"

block/bfq-iosched.c

@@ -17,7 +17,7 @@
  * low-latency capabilities. BFQ also supports full hierarchical
  * scheduling through cgroups. Next paragraphs provide an introduction
  * on BFQ inner workings. Details on BFQ benefits, usage and
- * limitations can be found in Documentation/block/bfq-iosched.txt.
+ * limitations can be found in Documentation/block/bfq-iosched.rst.
  *
  * BFQ is a proportional-share storage-I/O scheduling algorithm based
  * on the slice-by-slice service scheme of CFQ. But BFQ assigns

block/blk-integrity.c

@@ -383,7 +383,7 @@ static const struct blk_integrity_profile nop_profile = {
  * send/receive integrity metadata it must use this function to register
  * the capability with the block layer. The template is a blk_integrity
  * struct with values appropriate for the underlying hardware. See
- * Documentation/block/data-integrity.txt.
+ * Documentation/block/data-integrity.rst.
  */
 void blk_integrity_register(struct gendisk *disk, struct blk_integrity *template)
 {

block/ioprio.c

@@ -17,7 +17,7 @@
  *
  * ioprio_set(PRIO_PROCESS, pid, prio);
  *
- * See also Documentation/block/ioprio.txt
+ * See also Documentation/block/ioprio.rst
  *
  */
 #include <linux/gfp.h>

block/mq-deadline.c

@@ -25,7 +25,7 @@
 #include "blk-mq-sched.h"
 
 /*
- * See Documentation/block/deadline-iosched.txt
+ * See Documentation/block/deadline-iosched.rst
  */
 static const int read_expire = HZ / 2;  /* max time before a read is submitted. */
 static const int write_expire = 5 * HZ; /* ditto for writes, these limits are SOFT! */

block/partitions/cmdline.c

@@ -11,7 +11,7 @@
  *
  * The format for the command line is just like mtdparts.
  *
- * For further information, see "Documentation/block/cmdline-partition.txt"
+ * For further information, see "Documentation/block/cmdline-partition.rst"
  *
  */