[PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

[PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

The API described at sysfs.txt is deprecated.

Still, as it is still part of the Kernel (and will likely be
there for some time, as we don't simply remove APIs). So,
it makes sense to keep it there.

The conversion of this file is trivial:
  - add blank lines and identation in order to identify paragraphs;
  - mark a literal block as such.

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/gpio/index.rst                | 17 +++++++++
 Documentation/gpio/{sysfs.txt => sysfs.rst} | 39 +++++++++++++--------
 2 files changed, 42 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/gpio/index.rst
 rename Documentation/gpio/{sysfs.txt => sysfs.rst} (86%)

diff --git a/Documentation/gpio/index.rst b/Documentation/gpio/index.rst
new file mode 100644
index 000000000000..09a4a553f434
--- /dev/null
+++ b/Documentation/gpio/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+====
+gpio
+====
+
+.. toctree::
+    :maxdepth: 1
+
+    sysfs
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.rst
similarity index 86%
rename from Documentation/gpio/sysfs.txt
rename to Documentation/gpio/sysfs.rst
index 58eeab81f349..ec09ffd983e7 100644
--- a/Documentation/gpio/sysfs.txt
+++ b/Documentation/gpio/sysfs.rst
@@ -1,10 +1,12 @@
 GPIO Sysfs Interface for Userspace
 ==================================
 
-THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
-Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
-ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
-NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
+.. warning::
+
+  THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
+  Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
+  ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
+  NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
 
 Refer to the examples in tools/gpio/* for an introduction to the new
 character device ABI. Also see the userspace header in
@@ -51,13 +53,15 @@ The control interfaces are write-only:
 
     /sys/class/gpio/
 
-    	"export" ... Userspace may ask the kernel to export control of
+	"export" ...
+		Userspace may ask the kernel to export control of
 		a GPIO to userspace by writing its number to this file.
 
 		Example:  "echo 19 > export" will create a "gpio19" node
 		for GPIO #19, if that's not requested by kernel code.
 
-    	"unexport" ... Reverses the effect of exporting to userspace.
+	"unexport" ...
+		Reverses the effect of exporting to userspace.
 
 		Example:  "echo 19 > unexport" will remove a "gpio19"
 		node exported using the "export" file.
@@ -67,7 +71,8 @@ and have the following read/write attributes:
 
     /sys/class/gpio/gpioN/
 
-	"direction" ... reads as either "in" or "out". This value may
+	"direction" ...
+		reads as either "in" or "out". This value may
 		normally be written. Writing as "out" defaults to
 		initializing the value as low. To ensure glitch free
 		operation, values "low" and "high" may be written to
@@ -78,7 +83,8 @@ and have the following read/write attributes:
 		it was exported by kernel code that didn't explicitly
 		allow userspace to reconfigure this GPIO's direction.
 
-	"value" ... reads as either 0 (low) or 1 (high). If the GPIO
+	"value" ...
+		reads as either 0 (low) or 1 (high). If the GPIO
 		is configured as an output, this value may be written;
 		any nonzero value is treated as high.
 
@@ -92,14 +98,16 @@ and have the following read/write attributes:
 		file and read the new value or close the file and re-open it
 		to read the value.
 
-	"edge" ... reads as either "none", "rising", "falling", or
+	"edge" ...
+		reads as either "none", "rising", "falling", or
 		"both". Write these strings to select the signal edge(s)
 		that will make poll(2) on the "value" file return.
 
 		This file exists only if the pin can be configured as an
 		interrupt generating input pin.
 
-	"active_low" ... reads as either 0 (false) or 1 (true). Write
+	"active_low" ...
+		reads as either 0 (false) or 1 (true). Write
 		any nonzero value to invert the value attribute both
 		for reading and writing. Existing and subsequent
 		poll(2) support configuration via the edge attribute
@@ -112,11 +120,14 @@ read-only attributes:
 
     /sys/class/gpio/gpiochipN/
 
-    	"base" ... same as N, the first GPIO managed by this chip
+	"base" ...
+		same as N, the first GPIO managed by this chip
 
-    	"label" ... provided for diagnostics (not always unique)
+	"label" ...
+		provided for diagnostics (not always unique)
 
-        "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1)
+	"ngpio" ...
+		how many GPIOs this manages (N to N + ngpio - 1)
 
 Board documentation should in most cases cover what GPIOs are used for
 what purposes. However, those numbers are not always stable; GPIOs on
@@ -129,7 +140,7 @@ the correct GPIO number to use for a given signal.
 Exporting from Kernel code
 --------------------------
 Kernel code can explicitly manage exports of GPIOs which have already been
-requested using gpio_request():
+requested using gpio_request()::
 
 	/* export the GPIO to userspace */
 	int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
-- 
2.20.1

Re: [PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

[Linus Walleij]

On Mon, Apr 22, 2019 at 3:28 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:

> The API described at sysfs.txt is deprecated.
>
> Still, as it is still part of the Kernel (and will likely be
> there for some time, as we don't simply remove APIs). So,
> it makes sense to keep it there.
>
> The conversion of this file is trivial:
>   - add blank lines and identation in order to identify paragraphs;
>   - mark a literal block as such.
>
> 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>

Acked-by: Linus Walleij <linus.walleij@linaro.org>

Same question as the v1: should I apply it or will you :)

Yours,
Linus Walleij

Re: [PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 13:23:50 +0200
Linus Walleij <linus.walleij@linaro.org> escreveu:

> On Mon, Apr 22, 2019 at 3:28 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> 
> > The API described at sysfs.txt is deprecated.
> >
> > Still, as it is still part of the Kernel (and will likely be
> > there for some time, as we don't simply remove APIs). So,
> > it makes sense to keep it there.
> >
> > The conversion of this file is trivial:
> >   - add blank lines and identation in order to identify paragraphs;
> >   - mark a literal block as such.
> >
> > 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>  
> 
> Acked-by: Linus Walleij <linus.walleij@linaro.org>
> 
> Same question as the v1: should I apply it or will you :)

I suspect that it would be better if it gets applied via
the GPIO tree, in order to reduce potential merge conflicts.

Regards,
Mauro

Re: [PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

[Linus Walleij]

On Mon, Apr 22, 2019 at 3:28 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:

> The API described at sysfs.txt is deprecated.
>
> Still, as it is still part of the Kernel (and will likely be
> there for some time, as we don't simply remove APIs). So,
> it makes sense to keep it there.
>
> The conversion of this file is trivial:
>   - add blank lines and identation in order to identify paragraphs;
>   - mark a literal block as such.
>
> 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>

Patch applied to the GPIO tree.

Yours,
Linus Walleij

[PATCH v2 48/79] docs: driver-model: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Convert the various documents at the driver-model, preparing
them to be part of the driver-api book.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

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/driver-api/gpio/driver.rst      |   2 +-
 .../driver-model/{binding.txt => binding.rst} |  20 +-
 .../driver-model/{bus.txt => bus.rst}         |  69 ++--
 .../driver-model/{class.txt => class.rst}     |  74 ++--
 ...esign-patterns.txt => design-patterns.rst} | 106 +++---
 .../driver-model/{device.txt => device.rst}   |  57 +--
 .../driver-model/{devres.txt => devres.rst}   |  50 +--
 .../driver-model/{driver.txt => driver.rst}   | 112 +++---
 Documentation/driver-model/index.rst          |  26 ++
 .../{overview.txt => overview.rst}            |  37 +-
 .../{platform.txt => platform.rst}            |  30 +-
 .../driver-model/{porting.txt => porting.rst} | 333 +++++++++---------
 Documentation/eisa.txt                        |   4 +-
 Documentation/hwmon/submitting-patches.rst    |   2 +-
 drivers/base/platform.c                       |   2 +-
 drivers/gpio/gpio-cs5535.c                    |   2 +-
 drivers/net/ethernet/intel/ice/ice_main.c     |   2 +-
 scripts/coccinelle/free/devm_free.cocci       |   2 +-
 18 files changed, 489 insertions(+), 441 deletions(-)
 rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
 rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
 rename Documentation/driver-model/{class.txt => class.rst} (75%)
 rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
 rename Documentation/driver-model/{device.txt => device.rst} (71%)
 rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
 rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
 create mode 100644 Documentation/driver-model/index.rst
 rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
 rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
 rename Documentation/driver-model/{porting.txt => porting.rst} (62%)

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 3043167fc557..0eb083baab9e 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -303,7 +303,7 @@ symbol:
   the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks
   need to embed the gpio_chip in its state container and obtain a pointer
   to the container using container_of().
-  (See Documentation/driver-model/design-patterns.txt)
+  (See Documentation/driver-model/design-patterns.rst)
 
 * gpiochip_irqchip_add_nested(): adds a nested irqchip to a gpiochip.
   Apart from that it works exactly like the chained irqchip.
diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.rst
similarity index 92%
rename from Documentation/driver-model/binding.txt
rename to Documentation/driver-model/binding.rst
index abfc8e290d53..7ea1d7a41e1d 100644
--- a/Documentation/driver-model/binding.txt
+++ b/Documentation/driver-model/binding.rst
@@ -1,5 +1,6 @@
-
+==============
 Driver Binding
+==============
 
 Driver binding is the process of associating a device with a device
 driver that can control it. Bus drivers have typically handled this
@@ -25,7 +26,7 @@ device_register
 When a new device is added, the bus's list of drivers is iterated over
 to find one that supports it. In order to determine that, the device
 ID of the device must match one of the device IDs that the driver
-supports. The format and semantics for comparing IDs is bus-specific. 
+supports. The format and semantics for comparing IDs is bus-specific.
 Instead of trying to derive a complex state machine and matching
 algorithm, it is up to the bus driver to provide a callback to compare
 a device against the IDs of a driver. The bus returns 1 if a match was
@@ -36,14 +37,14 @@ int match(struct device * dev, struct device_driver * drv);
 If a match is found, the device's driver field is set to the driver
 and the driver's probe callback is called. This gives the driver a
 chance to verify that it really does support the hardware, and that
-it's in a working state. 
+it's in a working state.
 
 Device Class
 ~~~~~~~~~~~~
 
 Upon the successful completion of probe, the device is registered with
 the class to which it belongs. Device drivers belong to one and only one
-class, and that is set in the driver's devclass field. 
+class, and that is set in the driver's devclass field.
 devclass_add_device is called to enumerate the device within the class
 and actually register it with the class, which happens with the
 class's register_dev callback.
@@ -53,7 +54,7 @@ Driver
 ~~~~~~
 
 When a driver is attached to a device, the device is inserted into the
-driver's list of devices. 
+driver's list of devices.
 
 
 sysfs
@@ -67,18 +68,18 @@ to the device's directory in the physical hierarchy.
 
 A directory for the device is created in the class's directory. A
 symlink is created in that directory that points to the device's
-physical location in the sysfs tree. 
+physical location in the sysfs tree.
 
 A symlink can be created (though this isn't done yet) in the device's
 physical directory to either its class directory, or the class's
 top-level directory. One can also be created to point to its driver's
-directory also. 
+directory also.
 
 
 driver_register
 ~~~~~~~~~~~~~~~
 
-The process is almost identical for when a new driver is added. 
+The process is almost identical for when a new driver is added.
 The bus's list of devices is iterated over to find a match. Devices
 that already have a driver are skipped. All the devices are iterated
 over, to bind as many devices as possible to the driver.
@@ -94,5 +95,4 @@ of the driver is decremented. All symlinks between the two are removed.
 
 When a driver is removed, the list of devices that it supports is
 iterated over, and the driver's remove callback is called for each
-one. The device is removed from that list and the symlinks removed. 
-
+one. The device is removed from that list and the symlinks removed.
diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.rst
similarity index 76%
rename from Documentation/driver-model/bus.txt
rename to Documentation/driver-model/bus.rst
index c247b488a567..016b15a6e8ea 100644
--- a/Documentation/driver-model/bus.txt
+++ b/Documentation/driver-model/bus.rst
@@ -1,5 +1,6 @@
-
-Bus Types 
+=========
+Bus Types
+=========
 
 Definition
 ~~~~~~~~~~
@@ -13,12 +14,12 @@ Declaration
 
 Each bus type in the kernel (PCI, USB, etc) should declare one static
 object of this type. They must initialize the name field, and may
-optionally initialize the match callback.
+optionally initialize the match callback::
 
-struct bus_type pci_bus_type = {
-       .name	= "pci",
-       .match	= pci_bus_match,
-};
+   struct bus_type pci_bus_type = {
+          .name	= "pci",
+          .match	= pci_bus_match,
+   };
 
 The structure should be exported to drivers in a header file:
 
@@ -30,8 +31,8 @@ Registration
 
 When a bus driver is initialized, it calls bus_register. This
 initializes the rest of the fields in the bus object and inserts it
-into a global list of bus types. Once the bus object is registered, 
-the fields in it are usable by the bus driver. 
+into a global list of bus types. Once the bus object is registered,
+the fields in it are usable by the bus driver.
 
 
 Callbacks
@@ -43,17 +44,17 @@ match(): Attaching Drivers to Devices
 The format of device ID structures and the semantics for comparing
 them are inherently bus-specific. Drivers typically declare an array
 of device IDs of devices they support that reside in a bus-specific
-driver structure. 
+driver structure.
 
 The purpose of the match callback is to give the bus an opportunity to
 determine if a particular driver supports a particular device by
 comparing the device IDs the driver supports with the device ID of a
 particular device, without sacrificing bus-specific functionality or
-type-safety. 
+type-safety.
 
 When a driver is registered with the bus, the bus's list of devices is
 iterated over, and the match callback is called for each device that
-does not have a driver associated with it. 
+does not have a driver associated with it.
 
 
 
@@ -64,22 +65,23 @@ The lists of devices and drivers are intended to replace the local
 lists that many buses keep. They are lists of struct devices and
 struct device_drivers, respectively. Bus drivers are free to use the
 lists as they please, but conversion to the bus-specific type may be
-necessary. 
+necessary.
 
-The LDM core provides helper functions for iterating over each list.
+The LDM core provides helper functions for iterating over each list::
 
-int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,
-		     int (*fn)(struct device *, void *));
+  int bus_for_each_dev(struct bus_type * bus, struct device * start,
+		       void * data,
+		       int (*fn)(struct device *, void *));
 
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, 
-		     void * data, int (*fn)(struct device_driver *, void *));
+  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+		       void * data, int (*fn)(struct device_driver *, void *));
 
 These helpers iterate over the respective list, and call the callback
 for each device or driver in the list. All list accesses are
 synchronized by taking the bus's lock (read currently). The reference
 count on each object in the list is incremented before the callback is
 called; it is decremented after the next object has been obtained. The
-lock is not held when calling the callback. 
+lock is not held when calling the callback.
 
 
 sysfs
@@ -87,14 +89,14 @@ sysfs
 There is a top-level directory named 'bus'.
 
 Each bus gets a directory in the bus directory, along with two default
-directories:
+directories::
 
 	/sys/bus/pci/
 	|-- devices
 	`-- drivers
 
 Drivers registered with the bus get a directory in the bus's drivers
-directory:
+directory::
 
 	/sys/bus/pci/
 	|-- devices
@@ -106,7 +108,7 @@ directory:
 
 Each device that is discovered on a bus of that type gets a symlink in
 the bus's devices directory to the device's directory in the physical
-hierarchy:
+hierarchy::
 
 	/sys/bus/pci/
 	|-- devices
@@ -118,26 +120,27 @@ hierarchy:
 
 Exporting Attributes
 ~~~~~~~~~~~~~~~~~~~~
-struct bus_attribute {
+
+::
+
+  struct bus_attribute {
 	struct attribute	attr;
 	ssize_t (*show)(struct bus_type *, char * buf);
 	ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
+  };
 
 Bus drivers can export attributes using the BUS_ATTR_RW macro that works
 similarly to the DEVICE_ATTR_RW macro for devices. For example, a
-definition like this:
+definition like this::
 
-static BUS_ATTR_RW(debug);
+	static BUS_ATTR_RW(debug);
 
-is equivalent to declaring:
+is equivalent to declaring::
 
-static bus_attribute bus_attr_debug;
+	static bus_attribute bus_attr_debug;
 
 This can then be used to add and remove the attribute from the bus's
-sysfs directory using:
-
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
-
+sysfs directory using::
 
+	int bus_create_file(struct bus_type *, struct bus_attribute *);
+	void bus_remove_file(struct bus_type *, struct bus_attribute *);
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.rst
similarity index 75%
rename from Documentation/driver-model/class.txt
rename to Documentation/driver-model/class.rst
index 1fefc480a80b..fff55b80e86a 100644
--- a/Documentation/driver-model/class.txt
+++ b/Documentation/driver-model/class.rst
@@ -1,6 +1,6 @@
-
+==============
 Device Classes
-
+==============
 
 Introduction
 ~~~~~~~~~~~~
@@ -13,37 +13,37 @@ device. The following device classes have been identified:
 Each device class defines a set of semantics and a programming interface
 that devices of that class adhere to. Device drivers are the
 implementation of that programming interface for a particular device on
-a particular bus. 
+a particular bus.
 
 Device classes are agnostic with respect to what bus a device resides
-on. 
+on.
 
 
 Programming Interface
 ~~~~~~~~~~~~~~~~~~~~~
-The device class structure looks like: 
+The device class structure looks like::
 
 
-typedef int (*devclass_add)(struct device *);
-typedef void (*devclass_remove)(struct device *);
+  typedef int (*devclass_add)(struct device *);
+  typedef void (*devclass_remove)(struct device *);
 
 See the kerneldoc for the struct class.
 
-A typical device class definition would look like: 
+A typical device class definition would look like::
 
-struct device_class input_devclass = {
+  struct device_class input_devclass = {
         .name		= "input",
         .add_device	= input_add_device,
 	.remove_device	= input_remove_device,
-};
+  };
 
 Each device class structure should be exported in a header file so it
 can be used by drivers, extensions and interfaces.
 
-Device classes are registered and unregistered with the core using: 
+Device classes are registered and unregistered with the core using::
 
-int devclass_register(struct device_class * cls);
-void devclass_unregister(struct device_class * cls);
+  int devclass_register(struct device_class * cls);
+  void devclass_unregister(struct device_class * cls);
 
 
 Devices
@@ -52,16 +52,16 @@ As devices are bound to drivers, they are added to the device class
 that the driver belongs to. Before the driver model core, this would
 typically happen during the driver's probe() callback, once the device
 has been initialized. It now happens after the probe() callback
-finishes from the core. 
+finishes from the core.
 
 The device is enumerated in the class. Each time a device is added to
 the class, the class's devnum field is incremented and assigned to the
 device. The field is never decremented, so if the device is removed
 from the class and re-added, it will receive a different enumerated
-value. 
+value.
 
 The class is allowed to create a class-specific structure for the
-device and store it in the device's class_data pointer. 
+device and store it in the device's class_data pointer.
 
 There is no list of devices in the device class. Each driver has a
 list of devices that it supports. The device class has a list of
@@ -73,15 +73,15 @@ Device Drivers
 ~~~~~~~~~~~~~~
 Device drivers are added to device classes when they are registered
 with the core. A driver specifies the class it belongs to by setting
-the struct device_driver::devclass field. 
+the struct device_driver::devclass field.
 
 
 sysfs directory structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is a top-level sysfs directory named 'class'. 
+There is a top-level sysfs directory named 'class'.
 
 Each class gets a directory in the class directory, along with two
-default subdirectories:
+default subdirectories::
 
         class/
         `-- input
@@ -89,8 +89,8 @@ default subdirectories:
             `-- drivers
 
 
-Drivers registered with the class get a symlink in the drivers/ directory 
-that points to the driver's directory (under its bus directory):
+Drivers registered with the class get a symlink in the drivers/ directory
+that points to the driver's directory (under its bus directory)::
 
    class/
    `-- input
@@ -99,8 +99,8 @@ that points to the driver's directory (under its bus directory):
            `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
 
 
-Each device gets a symlink in the devices/ directory that points to the 
-device's directory in the physical hierarchy:
+Each device gets a symlink in the devices/ directory that points to the
+device's directory in the physical hierarchy::
 
    class/
    `-- input
@@ -111,37 +111,39 @@ device's directory in the physical hierarchy:
 
 Exporting Attributes
 ~~~~~~~~~~~~~~~~~~~~
-struct devclass_attribute {
+
+::
+
+  struct devclass_attribute {
         struct attribute        attr;
         ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
         ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
-};
+  };
 
 Class drivers can export attributes using the DEVCLASS_ATTR macro that works
-similarly to the DEVICE_ATTR macro for devices. For example, a definition 
-like this:
+similarly to the DEVICE_ATTR macro for devices. For example, a definition
+like this::
 
-static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
+  static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
 
-is equivalent to declaring:
+is equivalent to declaring::
 
-static devclass_attribute devclass_attr_debug;
+  static devclass_attribute devclass_attr_debug;
 
 The bus driver can add and remove the attribute from the class's
-sysfs directory using:
+sysfs directory using::
 
-int devclass_create_file(struct device_class *, struct devclass_attribute *);
-void devclass_remove_file(struct device_class *, struct devclass_attribute *);
+  int devclass_create_file(struct device_class *, struct devclass_attribute *);
+  void devclass_remove_file(struct device_class *, struct devclass_attribute *);
 
 In the example above, the file will be named 'debug' in placed in the
-class's directory in sysfs. 
+class's directory in sysfs.
 
 
 Interfaces
 ~~~~~~~~~~
 There may exist multiple mechanisms for accessing the same device of a
-particular class type. Device interfaces describe these mechanisms. 
+particular class type. Device interfaces describe these mechanisms.
 
 When a device is added to a device class, the core attempts to add it
 to every interface that is registered with the device class.
-
diff --git a/Documentation/driver-model/design-patterns.txt b/Documentation/driver-model/design-patterns.rst
similarity index 59%
rename from Documentation/driver-model/design-patterns.txt
rename to Documentation/driver-model/design-patterns.rst
index ba7b2df64904..41eb8f41f7dd 100644
--- a/Documentation/driver-model/design-patterns.txt
+++ b/Documentation/driver-model/design-patterns.rst
@@ -1,6 +1,6 @@
-
+=============================
 Device Driver Design Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
 
 This document describes a few common design patterns found in device drivers.
 It is likely that subsystem maintainers will ask driver developers to
@@ -19,23 +19,23 @@ that the device the driver binds to will appear in several instances. This
 means that the probe() function and all callbacks need to be reentrant.
 
 The most common way to achieve this is to use the state container design
-pattern. It usually has this form:
+pattern. It usually has this form::
 
-struct foo {
-    spinlock_t lock; /* Example member */
-    (...)
-};
+  struct foo {
+      spinlock_t lock; /* Example member */
+      (...)
+  };
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
-    if (!foo)
-        return -ENOMEM;
-    spin_lock_init(&foo->lock);
-    (...)
-}
+      foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
+      if (!foo)
+          return -ENOMEM;
+      spin_lock_init(&foo->lock);
+      (...)
+  }
 
 This will create an instance of struct foo in memory every time probe() is
 called. This is our state container for this instance of the device driver.
@@ -43,21 +43,21 @@ Of course it is then necessary to always pass this instance of the
 state around to all functions that need access to the state and its members.
 
 For example, if the driver is registering an interrupt handler, you would
-pass around a pointer to struct foo like this:
+pass around a pointer to struct foo like this::
 
-static irqreturn_t foo_handler(int irq, void *arg)
-{
-    struct foo *foo = arg;
-    (...)
-}
+  static irqreturn_t foo_handler(int irq, void *arg)
+  {
+      struct foo *foo = arg;
+      (...)
+  }
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    (...)
-    ret = request_irq(irq, foo_handler, 0, "foo", foo);
-}
+      (...)
+      ret = request_irq(irq, foo_handler, 0, "foo", foo);
+  }
 
 This way you always get a pointer back to the correct instance of foo in
 your interrupt handler.
@@ -66,38 +66,38 @@ your interrupt handler.
 2. container_of()
 ~~~~~~~~~~~~~~~~~
 
-Continuing on the above example we add an offloaded work:
+Continuing on the above example we add an offloaded work::
 
-struct foo {
-    spinlock_t lock;
-    struct workqueue_struct *wq;
-    struct work_struct offload;
-    (...)
-};
+  struct foo {
+      spinlock_t lock;
+      struct workqueue_struct *wq;
+      struct work_struct offload;
+      (...)
+  };
 
-static void foo_work(struct work_struct *work)
-{
-    struct foo *foo = container_of(work, struct foo, offload);
+  static void foo_work(struct work_struct *work)
+  {
+      struct foo *foo = container_of(work, struct foo, offload);
 
-    (...)
-}
+      (...)
+  }
 
-static irqreturn_t foo_handler(int irq, void *arg)
-{
-    struct foo *foo = arg;
+  static irqreturn_t foo_handler(int irq, void *arg)
+  {
+      struct foo *foo = arg;
 
-    queue_work(foo->wq, &foo->offload);
-    (...)
-}
+      queue_work(foo->wq, &foo->offload);
+      (...)
+  }
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    foo->wq = create_singlethread_workqueue("foo-wq");
-    INIT_WORK(&foo->offload, foo_work);
-    (...)
-}
+      foo->wq = create_singlethread_workqueue("foo-wq");
+      INIT_WORK(&foo->offload, foo_work);
+      (...)
+  }
 
 The design pattern is the same for an hrtimer or something similar that will
 return a single argument which is a pointer to a struct member in the
diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.rst
similarity index 71%
rename from Documentation/driver-model/device.txt
rename to Documentation/driver-model/device.rst
index 2403eb856187..2b868d49d349 100644
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.rst
@@ -1,6 +1,6 @@
-
+==========================
 The Basic Device Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
 
 See the kerneldoc for the struct device.
 
@@ -8,9 +8,9 @@ See the kerneldoc for the struct device.
 Programming Interface
 ~~~~~~~~~~~~~~~~~~~~~
 The bus driver that discovers the device uses this to register the
-device with the core:
+device with the core::
 
-int device_register(struct device * dev);
+  int device_register(struct device * dev);
 
 The bus should initialize the following fields:
 
@@ -20,30 +20,33 @@ The bus should initialize the following fields:
     - bus
 
 A device is removed from the core when its reference count goes to
-0. The reference count can be adjusted using:
+0. The reference count can be adjusted using::
 
-struct device * get_device(struct device * dev);
-void put_device(struct device * dev);
+  struct device * get_device(struct device * dev);
+  void put_device(struct device * dev);
 
 get_device() will return a pointer to the struct device passed to it
 if the reference is not already 0 (if it's in the process of being
 removed already).
 
-A driver can access the lock in the device structure using: 
+A driver can access the lock in the device structure using::
 
-void lock_device(struct device * dev);
-void unlock_device(struct device * dev);
+  void lock_device(struct device * dev);
+  void unlock_device(struct device * dev);
 
 
 Attributes
 ~~~~~~~~~~
-struct device_attribute {
+
+::
+
+  struct device_attribute {
 	struct attribute	attr;
 	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 			char *buf);
 	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 			 const char *buf, size_t count);
-};
+  };
 
 Attributes of devices can be exported by a device driver through sysfs.
 
@@ -54,39 +57,39 @@ As explained in Documentation/kobject.txt, device attributes must be
 created before the KOBJ_ADD uevent is generated. The only way to realize
 that is by defining an attribute group.
 
-Attributes are declared using a macro called DEVICE_ATTR:
+Attributes are declared using a macro called DEVICE_ATTR::
 
-#define DEVICE_ATTR(name,mode,show,store)
+  #define DEVICE_ATTR(name,mode,show,store)
 
-Example:
+Example:::
 
-static DEVICE_ATTR(type, 0444, show_type, NULL);
-static DEVICE_ATTR(power, 0644, show_power, store_power);
+  static DEVICE_ATTR(type, 0444, show_type, NULL);
+  static DEVICE_ATTR(power, 0644, show_power, store_power);
 
 This declares two structures of type struct device_attribute with respective
 names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be
-organized as follows into a group:
+organized as follows into a group::
 
-static struct attribute *dev_attrs[] = {
+  static struct attribute *dev_attrs[] = {
 	&dev_attr_type.attr,
 	&dev_attr_power.attr,
 	NULL,
-};
+  };
 
-static struct attribute_group dev_attr_group = {
+  static struct attribute_group dev_attr_group = {
 	.attrs = dev_attrs,
-};
+  };
 
-static const struct attribute_group *dev_attr_groups[] = {
+  static const struct attribute_group *dev_attr_groups[] = {
 	&dev_attr_group,
 	NULL,
-};
+  };
 
 This array of groups can then be associated with a device by setting the
-group pointer in struct device before device_register() is invoked:
+group pointer in struct device before device_register() is invoked::
 
-      dev->groups = dev_attr_groups;
-      device_register(dev);
+        dev->groups = dev_attr_groups;
+        device_register(dev);
 
 The device_register() function will use the 'groups' pointer to create the
 device attributes and the device_unregister() function will use this pointer
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.rst
similarity index 93%
rename from Documentation/driver-model/devres.txt
rename to Documentation/driver-model/devres.rst
index 99994a461359..4f88bdd7d555 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.rst
@@ -1,3 +1,4 @@
+================================
 Devres - Managed Device Resource
 ================================
 
@@ -5,17 +6,18 @@ Tejun Heo	<teheo@suse.de>
 
 First draft	10 January 2007
 
+.. contents
 
-1. Intro			: Huh? Devres?
-2. Devres			: Devres in a nutshell
-3. Devres Group			: Group devres'es and release them together
-4. Details			: Life time rules, calling context, ...
-5. Overhead			: How much do we have to pay for this?
-6. List of managed interfaces	: Currently implemented managed interfaces
+   1. Intro			: Huh? Devres?
+   2. Devres			: Devres in a nutshell
+   3. Devres Group		: Group devres'es and release them together
+   4. Details			: Life time rules, calling context, ...
+   5. Overhead			: How much do we have to pay for this?
+   6. List of managed interfaces: Currently implemented managed interfaces
 
 
-  1. Intro
-  --------
+1. Intro
+--------
 
 devres came up while trying to convert libata to use iomap.  Each
 iomapped address should be kept and unmapped on driver detach.  For
@@ -42,8 +44,8 @@ would leak resources or even cause oops when failure occurs.  iomap
 adds more to this mix.  So do msi and msix.
 
 
-  2. Devres
-  ---------
+2. Devres
+---------
 
 devres is basically linked list of arbitrarily sized memory areas
 associated with a struct device.  Each devres entry is associated with
@@ -58,7 +60,7 @@ using dma_alloc_coherent().  The managed version is called
 dmam_alloc_coherent().  It is identical to dma_alloc_coherent() except
 for the DMA memory allocated using it is managed and will be
 automatically released on driver detach.  Implementation looks like
-the following.
+the following::
 
   struct dma_devres {
 	size_t		size;
@@ -98,7 +100,7 @@ If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
 freed whether initialization fails half-way or the device gets
 detached.  If most resources are acquired using managed interface, a
 driver can have much simpler init and exit code.  Init path basically
-looks like the following.
+looks like the following::
 
   my_init_one()
   {
@@ -119,7 +121,7 @@ looks like the following.
 	return register_to_upper_layer(d);
   }
 
-And exit path,
+And exit path::
 
   my_remove_one()
   {
@@ -140,13 +142,13 @@ on you. In some cases this may mean introducing checks that were not
 necessary before moving to the managed devm_* calls.
 
 
-  3. Devres group
-  ---------------
+3. Devres group
+---------------
 
 Devres entries can be grouped using devres group.  When a group is
 released, all contained normal devres entries and properly nested
 groups are released.  One usage is to rollback series of acquired
-resources on failure.  For example,
+resources on failure.  For example::
 
   if (!devres_open_group(dev, NULL, GFP_KERNEL))
 	return -ENOMEM;
@@ -172,7 +174,7 @@ like above are usually useful in midlayer driver (e.g. libata core
 layer) where interface function shouldn't have side effect on failure.
 For LLDs, just returning error code suffices in most cases.
 
-Each group is identified by void *id.  It can either be explicitly
+Each group is identified by `void *id`.  It can either be explicitly
 specified by @id argument to devres_open_group() or automatically
 created by passing NULL as @id as in the above example.  In both
 cases, devres_open_group() returns the group's id.  The returned id
@@ -180,7 +182,7 @@ can be passed to other devres functions to select the target group.
 If NULL is given to those functions, the latest open group is
 selected.
 
-For example, you can do something like the following.
+For example, you can do something like the following::
 
   int my_midlayer_create_something()
   {
@@ -199,8 +201,8 @@ For example, you can do something like the following.
   }
 
 
-  4. Details
-  ----------
+4. Details
+----------
 
 Lifetime of a devres entry begins on devres allocation and finishes
 when it is released or destroyed (removed and freed) - no reference
@@ -220,8 +222,8 @@ All devres interface functions can be called without context if the
 right gfp mask is given.
 
 
-  5. Overhead
-  -----------
+5. Overhead
+-----------
 
 Each devres bookkeeping info is allocated together with requested data
 area.  With debug option turned off, bookkeeping info occupies 16
@@ -237,8 +239,8 @@ and 400 bytes on 32bit machine after naive conversion (we can
 certainly invest a bit more effort into libata core layer).
 
 
-  6. List of managed interfaces
-  -----------------------------
+6. List of managed interfaces
+-----------------------------
 
 CLOCK
   devm_clk_get()
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.rst
similarity index 75%
rename from Documentation/driver-model/driver.txt
rename to Documentation/driver-model/driver.rst
index d661e6f7e6a0..11d281506a04 100644
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.rst
@@ -1,5 +1,6 @@
-
+==============
 Device Drivers
+==============
 
 See the kerneldoc for the struct device_driver.
 
@@ -26,50 +27,50 @@ Declaration
 As stated above, struct device_driver objects are statically
 allocated. Below is an example declaration of the eepro100
 driver. This declaration is hypothetical only; it relies on the driver
-being converted completely to the new model. 
+being converted completely to the new model::
 
-static struct device_driver eepro100_driver = {
-       .name		= "eepro100",
-       .bus		= &pci_bus_type,
-       
-       .probe		= eepro100_probe,
-       .remove		= eepro100_remove,
-       .suspend		= eepro100_suspend,
-       .resume		= eepro100_resume,
-};
+  static struct device_driver eepro100_driver = {
+         .name		= "eepro100",
+         .bus		= &pci_bus_type,
+
+         .probe		= eepro100_probe,
+         .remove		= eepro100_remove,
+         .suspend		= eepro100_suspend,
+         .resume		= eepro100_resume,
+  };
 
 Most drivers will not be able to be converted completely to the new
 model because the bus they belong to has a bus-specific structure with
-bus-specific fields that cannot be generalized. 
+bus-specific fields that cannot be generalized.
 
 The most common example of this are device ID structures. A driver
 typically defines an array of device IDs that it supports. The format
 of these structures and the semantics for comparing device IDs are
 completely bus-specific. Defining them as bus-specific entities would
-sacrifice type-safety, so we keep bus-specific structures around. 
+sacrifice type-safety, so we keep bus-specific structures around.
 
 Bus-specific drivers should include a generic struct device_driver in
-the definition of the bus-specific driver. Like this:
+the definition of the bus-specific driver. Like this::
 
-struct pci_driver {
-       const struct pci_device_id *id_table;
-       struct device_driver	  driver;
-};
+  struct pci_driver {
+         const struct pci_device_id *id_table;
+         struct device_driver	  driver;
+  };
 
 A definition that included bus-specific fields would look like
-(using the eepro100 driver again):
+(using the eepro100 driver again)::
 
-static struct pci_driver eepro100_driver = {
-       .id_table       = eepro100_pci_tbl,
-       .driver	       = {
+  static struct pci_driver eepro100_driver = {
+         .id_table       = eepro100_pci_tbl,
+         .driver	       = {
 		.name		= "eepro100",
 		.bus		= &pci_bus_type,
 		.probe		= eepro100_probe,
 		.remove		= eepro100_remove,
 		.suspend	= eepro100_suspend,
 		.resume		= eepro100_resume,
-       },
-};
+         },
+  };
 
 Some may find the syntax of embedded struct initialization awkward or
 even a bit ugly. So far, it's the best way we've found to do what we want...
@@ -77,12 +78,14 @@ even a bit ugly. So far, it's the best way we've found to do what we want...
 Registration
 ~~~~~~~~~~~~
 
-int driver_register(struct device_driver * drv);
+::
+
+  int driver_register(struct device_driver *drv);
 
 The driver registers the structure on startup. For drivers that have
 no bus-specific fields (i.e. don't have a bus-specific driver
 structure), they would use driver_register and pass a pointer to their
-struct device_driver object. 
+struct device_driver object.
 
 Most drivers, however, will have a bus-specific structure and will
 need to register with the bus using something like pci_driver_register.
@@ -101,7 +104,7 @@ By defining wrapper functions, the transition to the new model can be
 made easier. Drivers can ignore the generic structure altogether and
 let the bus wrapper fill in the fields. For the callbacks, the bus can
 define generic callbacks that forward the call to the bus-specific
-callbacks of the drivers. 
+callbacks of the drivers.
 
 This solution is intended to be only temporary. In order to get class
 information in the driver, the drivers must be modified anyway. Since
@@ -113,16 +116,16 @@ Access
 ~~~~~~
 
 Once the object has been registered, it may access the common fields of
-the object, like the lock and the list of devices. 
+the object, like the lock and the list of devices::
 
-int driver_for_each_dev(struct device_driver * drv, void * data, 
-		        int (*callback)(struct device * dev, void * data));
+  int driver_for_each_dev(struct device_driver *drv, void *data,
+			  int (*callback)(struct device *dev, void *data));
 
 The devices field is a list of all the devices that have been bound to
 the driver. The LDM core provides a helper function to operate on all
 the devices a driver controls. This helper locks the driver on each
 node access, and does proper reference counting on each device as it
-accesses it. 
+accesses it.
 
 
 sysfs
@@ -142,7 +145,9 @@ supports.
 Callbacks
 ~~~~~~~~~
 
-	int	(*probe)	(struct device * dev);
+::
+
+	int	(*probe)	(struct device *dev);
 
 The probe() entry is called in task context, with the bus's rwsem locked
 and the driver partially bound to the device.  Drivers commonly use
@@ -162,9 +167,9 @@ the driver to that device.
 
 A driver's probe() may return a negative errno value to indicate that
 the driver did not bind to this device, in which case it should have
-released all resources it allocated.
+released all resources it allocated::
 
-	int 	(*remove)	(struct device * dev);
+	int 	(*remove)	(struct device *dev);
 
 remove is called to unbind a driver from a device. This may be
 called if a device is physically removed from the system, if the
@@ -173,43 +178,46 @@ in other cases.
 
 It is up to the driver to determine if the device is present or
 not. It should free any resources allocated specifically for the
-device; i.e. anything in the device's driver_data field. 
+device; i.e. anything in the device's driver_data field.
 
 If the device is still present, it should quiesce the device and place
-it into a supported low-power state.
+it into a supported low-power state::
 
-	int	(*suspend)	(struct device * dev, pm_message_t state);
+	int	(*suspend)	(struct device *dev, pm_message_t state);
 
-suspend is called to put the device in a low power state.
+suspend is called to put the device in a low power state::
 
-	int	(*resume)	(struct device * dev);
+	int	(*resume)	(struct device *dev);
 
 Resume is used to bring a device back from a low power state.
 
 
 Attributes
 ~~~~~~~~~~
-struct driver_attribute {
-        struct attribute        attr;
-        ssize_t (*show)(struct device_driver *driver, char *buf);
-        ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
-};
 
-Device drivers can export attributes via their sysfs directories. 
+::
+
+  struct driver_attribute {
+          struct attribute        attr;
+          ssize_t (*show)(struct device_driver *driver, char *buf);
+          ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
+  };
+
+Device drivers can export attributes via their sysfs directories.
 Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
 macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
 macros.
 
-Example:
+Example::
 
-DRIVER_ATTR_RW(debug);
+	DRIVER_ATTR_RW(debug);
 
-This is equivalent to declaring:
+This is equivalent to declaring::
 
-struct driver_attribute driver_attr_debug;
+	struct driver_attribute driver_attr_debug;
 
 This can then be used to add and remove the attribute from the
-driver's directory using:
+driver's directory using::
 
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+  int driver_create_file(struct device_driver *, const struct driver_attribute *);
+  void driver_remove_file(struct device_driver *, const struct driver_attribute *);
diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst
new file mode 100644
index 000000000000..9f85d579ce56
--- /dev/null
+++ b/Documentation/driver-model/index.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+============
+Driver Model
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   binding
+   bus
+   class
+   design-patterns
+   device
+   devres
+   driver
+   overview
+   platform
+   porting
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.rst
similarity index 90%
rename from Documentation/driver-model/overview.txt
rename to Documentation/driver-model/overview.rst
index 6a8f9a8075d8..d4d1e9b40e0c 100644
--- a/Documentation/driver-model/overview.txt
+++ b/Documentation/driver-model/overview.rst
@@ -1,4 +1,6 @@
+=============================
 The Linux Kernel Device Model
+=============================
 
 Patrick Mochel	<mochel@digitalimplant.org>
 
@@ -41,14 +43,14 @@ data structure. These fields must still be accessed by the bus layers,
 and sometimes by the device-specific drivers.
 
 Other bus layers are encouraged to do what has been done for the PCI layer.
-struct pci_dev now looks like this:
+struct pci_dev now looks like this::
 
-struct pci_dev {
+  struct pci_dev {
 	...
 
 	struct device dev;     /* Generic device interface */
 	...
-};
+  };
 
 Note first that the struct device dev within the struct pci_dev is
 statically allocated. This means only one allocation on device discovery.
@@ -80,26 +82,26 @@ easy. This has been accomplished by implementing a special purpose virtual
 file system named sysfs.
 
 Almost all mainstream Linux distros mount this filesystem automatically; you
-can see some variation of the following in the output of the "mount" command:
+can see some variation of the following in the output of the "mount" command::
 
-$ mount
-...
-none on /sys type sysfs (rw,noexec,nosuid,nodev)
-...
-$
+  $ mount
+  ...
+  none on /sys type sysfs (rw,noexec,nosuid,nodev)
+  ...
+  $
 
 The auto-mounting of sysfs is typically accomplished by an entry similar to
-the following in the /etc/fstab file:
+the following in the /etc/fstab file::
 
-none     	/sys	sysfs    defaults	  	0 0
+  none     	/sys	sysfs    defaults	  	0 0
 
-or something similar in the /lib/init/fstab file on Debian-based systems:
+or something similar in the /lib/init/fstab file on Debian-based systems::
 
-none            /sys    sysfs    nodev,noexec,nosuid    0 0
+  none            /sys    sysfs    nodev,noexec,nosuid    0 0
 
-If sysfs is not automatically mounted, you can always do it manually with:
+If sysfs is not automatically mounted, you can always do it manually with::
 
-# mount -t sysfs sysfs /sys
+	# mount -t sysfs sysfs /sys
 
 Whenever a device is inserted into the tree, a directory is created for it.
 This directory may be populated at each layer of discovery - the global layer,
@@ -108,7 +110,7 @@ the bus layer, or the device layer.
 The global layer currently creates two files - 'name' and 'power'. The
 former only reports the name of the device. The latter reports the
 current power state of the device. It will also be used to set the current
-power state. 
+power state.
 
 The bus layer may also create files for the devices it finds while probing the
 bus. For example, the PCI layer currently creates 'irq' and 'resource' files
@@ -118,6 +120,5 @@ A device-specific driver may also export files in its directory to expose
 device-specific data or tunable interfaces.
 
 More information about the sysfs directory layout can be found in
-the other documents in this directory and in the file 
+the other documents in this directory and in the file
 Documentation/filesystems/sysfs.txt.
-
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.rst
similarity index 95%
rename from Documentation/driver-model/platform.txt
rename to Documentation/driver-model/platform.rst
index 9d9e47dfc013..334dd4071ae4 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.rst
@@ -1,5 +1,7 @@
+============================
 Platform Devices and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
+
 See <linux/platform_device.h> for the driver model interface to the
 platform bus:  platform_device, and platform_driver.  This pseudo-bus
 is used to connect devices on busses with minimal infrastructure,
@@ -19,15 +21,15 @@ be connected through a segment of some other kind of bus; but its
 registers will still be directly addressable.
 
 Platform devices are given a name, used in driver binding, and a
-list of resources such as addresses and IRQs.
+list of resources such as addresses and IRQs::
 
-struct platform_device {
+  struct platform_device {
 	const char	*name;
 	u32		id;
 	struct device	dev;
 	u32		num_resources;
 	struct resource	*resource;
-};
+  };
 
 
 Platform drivers
@@ -35,9 +37,9 @@ Platform drivers
 Platform drivers follow the standard driver model convention, where
 discovery/enumeration is handled outside the drivers, and drivers
 provide probe() and remove() methods.  They support power management
-and shutdown notifications using the standard conventions.
+and shutdown notifications using the standard conventions::
 
-struct platform_driver {
+  struct platform_driver {
 	int (*probe)(struct platform_device *);
 	int (*remove)(struct platform_device *);
 	void (*shutdown)(struct platform_device *);
@@ -46,25 +48,25 @@ struct platform_driver {
 	int (*resume_early)(struct platform_device *);
 	int (*resume)(struct platform_device *);
 	struct device_driver driver;
-};
+  };
 
 Note that probe() should in general verify that the specified device hardware
 actually exists; sometimes platform setup code can't be sure.  The probing
 can use device resources, including clocks, and device platform_data.
 
-Platform drivers register themselves the normal way:
+Platform drivers register themselves the normal way::
 
 	int platform_driver_register(struct platform_driver *drv);
 
 Or, in common situations where the device is known not to be hot-pluggable,
 the probe() routine can live in an init section to reduce the driver's
-runtime memory footprint:
+runtime memory footprint::
 
 	int platform_driver_probe(struct platform_driver *drv,
 			  int (*probe)(struct platform_device *))
 
 Kernel modules can be composed of several platform drivers. The platform core
-provides helpers to register and unregister an array of drivers:
+provides helpers to register and unregister an array of drivers::
 
 	int __platform_register_drivers(struct platform_driver * const *drivers,
 				      unsigned int count, struct module *owner);
@@ -73,7 +75,7 @@ provides helpers to register and unregister an array of drivers:
 
 If one of the drivers fails to register, all drivers registered up to that
 point will be unregistered in reverse order. Note that there is a convenience
-macro that passes THIS_MODULE as owner parameter:
+macro that passes THIS_MODULE as owner parameter::
 
 	#define platform_register_drivers(drivers, count)
 
@@ -81,7 +83,7 @@ macro that passes THIS_MODULE as owner parameter:
 Device Enumeration
 ~~~~~~~~~~~~~~~~~~
 As a rule, platform specific (and often board-specific) setup code will
-register platform devices:
+register platform devices::
 
 	int platform_device_register(struct platform_device *pdev);
 
@@ -133,14 +135,14 @@ tend to already have "normal" modes, such as ones using device nodes that
 were created by PNP or by platform device setup.
 
 None the less, there are some APIs to support such legacy drivers.  Avoid
-using these calls except with such hotplug-deficient drivers.
+using these calls except with such hotplug-deficient drivers::
 
 	struct platform_device *platform_device_alloc(
 			const char *name, int id);
 
 You can use platform_device_alloc() to dynamically allocate a device, which
 you will then initialize with resources and platform_device_register().
-A better solution is usually:
+A better solution is usually::
 
 	struct platform_device *platform_device_register_simple(
 			const char *name, int id,
diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.rst
similarity index 62%
rename from Documentation/driver-model/porting.txt
rename to Documentation/driver-model/porting.rst
index 453053f1661f..ae4bf843c1d6 100644
--- a/Documentation/driver-model/porting.txt
+++ b/Documentation/driver-model/porting.rst
@@ -1,5 +1,6 @@
-
+=======================================
 Porting Drivers to the New Driver Model
+=======================================
 
 Patrick Mochel
 
@@ -8,8 +9,8 @@ Patrick Mochel
 
 Overview
 
-Please refer to Documentation/driver-model/*.txt for definitions of
-various driver types and concepts. 
+Please refer to `Documentation/driver-model/*.rst` for definitions of
+various driver types and concepts.
 
 Most of the work of porting devices drivers to the new model happens
 at the bus driver layer. This was intentional, to minimize the
@@ -18,11 +19,11 @@ of bus drivers.
 
 In a nutshell, the driver model consists of a set of objects that can
 be embedded in larger, bus-specific objects. Fields in these generic
-objects can replace fields in the bus-specific objects. 
+objects can replace fields in the bus-specific objects.
 
 The generic objects must be registered with the driver model core. By
 doing so, they will exported via the sysfs filesystem. sysfs can be
-mounted by doing 
+mounted by doing::
 
 	# mount -t sysfs sysfs /sys
 
@@ -30,108 +31,109 @@ mounted by doing
 
 The Process
 
-Step 0: Read include/linux/device.h for object and function definitions. 
+Step 0: Read include/linux/device.h for object and function definitions.
 
-Step 1: Registering the bus driver. 
+Step 1: Registering the bus driver.
 
 
-- Define a struct bus_type for the bus driver.
+- Define a struct bus_type for the bus driver::
 
-struct bus_type pci_bus_type = {
-        .name           = "pci",
-};
+    struct bus_type pci_bus_type = {
+          .name           = "pci",
+    };
 
 
 - Register the bus type.
+
   This should be done in the initialization function for the bus type,
-  which is usually the module_init(), or equivalent, function. 
+  which is usually the module_init(), or equivalent, function::
 
-static int __init pci_driver_init(void)
-{
-        return bus_register(&pci_bus_type);
-}
+    static int __init pci_driver_init(void)
+    {
+            return bus_register(&pci_bus_type);
+    }
 
-subsys_initcall(pci_driver_init);
+    subsys_initcall(pci_driver_init);
 
 
   The bus type may be unregistered (if the bus driver may be compiled
-  as a module) by doing:
+  as a module) by doing::
 
      bus_unregister(&pci_bus_type);
 
 
-- Export the bus type for others to use. 
+- Export the bus type for others to use.
 
-  Other code may wish to reference the bus type, so declare it in a 
+  Other code may wish to reference the bus type, so declare it in a
   shared header file and export the symbol.
 
-From include/linux/pci.h:
+From include/linux/pci.h::
 
-extern struct bus_type pci_bus_type;
+  extern struct bus_type pci_bus_type;
 
 
-From file the above code appears in:
+From file the above code appears in::
 
-EXPORT_SYMBOL(pci_bus_type);
+  EXPORT_SYMBOL(pci_bus_type);
 
 
 
 - This will cause the bus to show up in /sys/bus/pci/ with two
-  subdirectories: 'devices' and 'drivers'.
+  subdirectories: 'devices' and 'drivers'::
 
-# tree -d /sys/bus/pci/
-/sys/bus/pci/
-|-- devices
-`-- drivers
+    # tree -d /sys/bus/pci/
+    /sys/bus/pci/
+    |-- devices
+    `-- drivers
 
 
 
-Step 2: Registering Devices. 
+Step 2: Registering Devices.
 
 struct device represents a single device. It mainly contains metadata
-describing the relationship the device has to other entities. 
+describing the relationship the device has to other entities.
 
 
-- Embed a struct device in the bus-specific device type. 
+- Embed a struct device in the bus-specific device type::
 
 
-struct pci_dev {
-       ...
-       struct  device  dev;            /* Generic device interface */
-       ...
-};
+    struct pci_dev {
+           ...
+           struct  device  dev;            /* Generic device interface */
+           ...
+    };
 
-  It is recommended that the generic device not be the first item in 
+  It is recommended that the generic device not be the first item in
   the struct to discourage programmers from doing mindless casts
   between the object types. Instead macros, or inline functions,
-  should be created to convert from the generic object type.
+  should be created to convert from the generic object type::
 
 
-#define to_pci_dev(n) container_of(n, struct pci_dev, dev)
+    #define to_pci_dev(n) container_of(n, struct pci_dev, dev)
 
-or 
+    or
 
-static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
-{
+    static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
+    {
 	return container_of(n, struct pci_dev, dev);
-}
+    }
 
-  This allows the compiler to verify type-safety of the operations 
+  This allows the compiler to verify type-safety of the operations
   that are performed (which is Good).
 
 
 - Initialize the device on registration.
 
-  When devices are discovered or registered with the bus type, the 
+  When devices are discovered or registered with the bus type, the
   bus driver should initialize the generic device. The most important
   things to initialize are the bus_id, parent, and bus fields.
 
   The bus_id is an ASCII string that contains the device's address on
   the bus. The format of this string is bus-specific. This is
-  necessary for representing devices in sysfs. 
+  necessary for representing devices in sysfs.
 
   parent is the physical parent of the device. It is important that
-  the bus driver sets this field correctly. 
+  the bus driver sets this field correctly.
 
   The driver model maintains an ordered list of devices that it uses
   for power management. This list must be in order to guarantee that
@@ -140,13 +142,13 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
   devices.
 
   Also, the location of the device's sysfs directory depends on a
-  device's parent. sysfs exports a directory structure that mirrors 
+  device's parent. sysfs exports a directory structure that mirrors
   the device hierarchy. Accurately setting the parent guarantees that
   sysfs will accurately represent the hierarchy.
 
   The device's bus field is a pointer to the bus type the device
   belongs to. This should be set to the bus_type that was declared
-  and initialized before. 
+  and initialized before.
 
   Optionally, the bus driver may set the device's name and release
   fields.
@@ -155,107 +157,107 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
 
      "ATI Technologies Inc Radeon QD"
 
-  The release field is a callback that the driver model core calls 
-  when the device has been removed, and all references to it have 
+  The release field is a callback that the driver model core calls
+  when the device has been removed, and all references to it have
   been released. More on this in a moment.
 
 
-- Register the device. 
+- Register the device.
 
   Once the generic device has been initialized, it can be registered
-  with the driver model core by doing:
+  with the driver model core by doing::
 
        device_register(&dev->dev);
 
-  It can later be unregistered by doing: 
+  It can later be unregistered by doing::
 
        device_unregister(&dev->dev);
 
-  This should happen on buses that support hotpluggable devices. 
+  This should happen on buses that support hotpluggable devices.
   If a bus driver unregisters a device, it should not immediately free
-  it. It should instead wait for the driver model core to call the 
-  device's release method, then free the bus-specific object. 
+  it. It should instead wait for the driver model core to call the
+  device's release method, then free the bus-specific object.
   (There may be other code that is currently referencing the device
-  structure, and it would be rude to free the device while that is 
+  structure, and it would be rude to free the device while that is
   happening).
 
 
-  When the device is registered, a directory in sysfs is created. 
-  The PCI tree in sysfs looks like: 
+  When the device is registered, a directory in sysfs is created.
+  The PCI tree in sysfs looks like::
 
-/sys/devices/pci0/
-|-- 00:00.0
-|-- 00:01.0
-|   `-- 01:00.0
-|-- 00:02.0
-|   `-- 02:1f.0
-|       `-- 03:00.0
-|-- 00:1e.0
-|   `-- 04:04.0
-|-- 00:1f.0
-|-- 00:1f.1
-|   |-- ide0
-|   |   |-- 0.0
-|   |   `-- 0.1
-|   `-- ide1
-|       `-- 1.0
-|-- 00:1f.2
-|-- 00:1f.3
-`-- 00:1f.5
+    /sys/devices/pci0/
+    |-- 00:00.0
+    |-- 00:01.0
+    |   `-- 01:00.0
+    |-- 00:02.0
+    |   `-- 02:1f.0
+    |       `-- 03:00.0
+    |-- 00:1e.0
+    |   `-- 04:04.0
+    |-- 00:1f.0
+    |-- 00:1f.1
+    |   |-- ide0
+    |   |   |-- 0.0
+    |   |   `-- 0.1
+    |   `-- ide1
+    |       `-- 1.0
+    |-- 00:1f.2
+    |-- 00:1f.3
+    `-- 00:1f.5
 
   Also, symlinks are created in the bus's 'devices' directory
-  that point to the device's directory in the physical hierarchy. 
+  that point to the device's directory in the physical hierarchy::
 
-/sys/bus/pci/devices/
-|-- 00:00.0 -> ../../../devices/pci0/00:00.0
-|-- 00:01.0 -> ../../../devices/pci0/00:01.0
-|-- 00:02.0 -> ../../../devices/pci0/00:02.0
-|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
-|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
-|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
-|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
-|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
-|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
-|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
-|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
-|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
-`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
+    /sys/bus/pci/devices/
+    |-- 00:00.0 -> ../../../devices/pci0/00:00.0
+    |-- 00:01.0 -> ../../../devices/pci0/00:01.0
+    |-- 00:02.0 -> ../../../devices/pci0/00:02.0
+    |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
+    |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
+    |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
+    |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
+    |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
+    |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
+    |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
+    |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
+    |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
+    `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
 
 
 
 Step 3: Registering Drivers.
 
 struct device_driver is a simple driver structure that contains a set
-of operations that the driver model core may call. 
+of operations that the driver model core may call.
 
 
-- Embed a struct device_driver in the bus-specific driver. 
+- Embed a struct device_driver in the bus-specific driver.
 
-  Just like with devices, do something like:
+  Just like with devices, do something like::
 
-struct pci_driver {
-       ...
-       struct device_driver    driver;
-};
+    struct pci_driver {
+           ...
+           struct device_driver    driver;
+    };
 
 
-- Initialize the generic driver structure. 
+- Initialize the generic driver structure.
 
   When the driver registers with the bus (e.g. doing pci_register_driver()),
   initialize the necessary fields of the driver: the name and bus
-  fields. 
+  fields.
 
 
 - Register the driver.
 
-  After the generic driver has been initialized, call
+  After the generic driver has been initialized, call::
 
 	driver_register(&drv->driver);
 
   to register the driver with the core.
 
   When the driver is unregistered from the bus, unregister it from the
-  core by doing:
+  core by doing::
 
         driver_unregister(&drv->driver);
 
@@ -265,15 +267,15 @@ struct pci_driver {
 
 - Sysfs representation.
 
-  Drivers are exported via sysfs in their bus's 'driver's directory. 
-  For example:
+  Drivers are exported via sysfs in their bus's 'driver's directory.
+  For example::
 
-/sys/bus/pci/drivers/
-|-- 3c59x
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|-- e100
-`-- serial
+    /sys/bus/pci/drivers/
+    |-- 3c59x
+    |-- Ensoniq AudioPCI
+    |-- agpgart-amdk7
+    |-- e100
+    `-- serial
 
 
 Step 4: Define Generic Methods for Drivers.
@@ -281,30 +283,30 @@ Step 4: Define Generic Methods for Drivers.
 struct device_driver defines a set of operations that the driver model
 core calls. Most of these operations are probably similar to
 operations the bus already defines for drivers, but taking different
-parameters. 
+parameters.
 
 It would be difficult and tedious to force every driver on a bus to
 simultaneously convert their drivers to generic format. Instead, the
 bus driver should define single instances of the generic methods that
-forward call to the bus-specific drivers. For instance: 
+forward call to the bus-specific drivers. For instance::
 
 
-static int pci_device_remove(struct device * dev)
-{
-        struct pci_dev * pci_dev = to_pci_dev(dev);
-        struct pci_driver * drv = pci_dev->driver;
+  static int pci_device_remove(struct device * dev)
+  {
+          struct pci_dev * pci_dev = to_pci_dev(dev);
+          struct pci_driver * drv = pci_dev->driver;
 
-        if (drv) {
-                if (drv->remove)
-                        drv->remove(pci_dev);
-                pci_dev->driver = NULL;
-        }
-        return 0;
-}
+          if (drv) {
+                  if (drv->remove)
+                          drv->remove(pci_dev);
+                  pci_dev->driver = NULL;
+          }
+          return 0;
+  }
 
 
 The generic driver should be initialized with these methods before it
-is registered. 
+is registered::
 
         /* initialize common driver fields */
         drv->driver.name = drv->name;
@@ -320,23 +322,23 @@ is registered.
 
 Ideally, the bus should only initialize the fields if they are not
 already set. This allows the drivers to implement their own generic
-methods. 
+methods.
 
 
-Step 5: Support generic driver binding. 
+Step 5: Support generic driver binding.
 
 The model assumes that a device or driver can be dynamically
 registered with the bus at any time. When registration happens,
 devices must be bound to a driver, or drivers must be bound to all
-devices that it supports. 
+devices that it supports.
 
 A driver typically contains a list of device IDs that it supports. The
-bus driver compares these IDs to the IDs of devices registered with it. 
+bus driver compares these IDs to the IDs of devices registered with it.
 The format of the device IDs, and the semantics for comparing them are
-bus-specific, so the generic model does attempt to generalize them. 
+bus-specific, so the generic model does attempt to generalize them.
 
 Instead, a bus may supply a method in struct bus_type that does the
-comparison: 
+comparison::
 
   int (*match)(struct device * dev, struct device_driver * drv);
 
@@ -346,59 +348,59 @@ and zero otherwise. It may also return error code (for example
 not possible.
 
 When a device is registered, the bus's list of drivers is iterated
-over. bus->match() is called for each one until a match is found. 
+over. bus->match() is called for each one until a match is found.
 
 When a driver is registered, the bus's list of devices is iterated
 over. bus->match() is called for each device that is not already
-claimed by a driver. 
+claimed by a driver.
 
 When a device is successfully bound to a driver, device->driver is
 set, the device is added to a per-driver list of devices, and a
 symlink is created in the driver's sysfs directory that points to the
-device's physical directory:
+device's physical directory::
 
-/sys/bus/pci/drivers/
-|-- 3c59x
-|   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
-|-- e100
-|   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
-`-- serial
+  /sys/bus/pci/drivers/
+  |-- 3c59x
+  |   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
+  |-- Ensoniq AudioPCI
+  |-- agpgart-amdk7
+  |   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
+  |-- e100
+  |   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
+  `-- serial
 
 
 This driver binding should replace the existing driver binding
-mechanism the bus currently uses. 
+mechanism the bus currently uses.
 
 
 Step 6: Supply a hotplug callback.
 
 Whenever a device is registered with the driver model core, the
-userspace program /sbin/hotplug is called to notify userspace. 
+userspace program /sbin/hotplug is called to notify userspace.
 Users can define actions to perform when a device is inserted or
-removed. 
+removed.
 
 The driver model core passes several arguments to userspace via
 environment variables, including
 
 - ACTION: set to 'add' or 'remove'
-- DEVPATH: set to the device's physical path in sysfs. 
+- DEVPATH: set to the device's physical path in sysfs.
 
 A bus driver may also supply additional parameters for userspace to
 consume. To do this, a bus must implement the 'hotplug' method in
-struct bus_type:
+struct bus_type::
 
-     int (*hotplug) (struct device *dev, char **envp, 
+     int (*hotplug) (struct device *dev, char **envp,
                      int num_envp, char *buffer, int buffer_size);
 
-This is called immediately before /sbin/hotplug is executed. 
+This is called immediately before /sbin/hotplug is executed.
 
 
 Step 7: Cleaning up the bus driver.
 
 The generic bus, device, and driver structures provide several fields
-that can replace those defined privately to the bus driver. 
+that can replace those defined privately to the bus driver.
 
 - Device list.
 
@@ -407,36 +409,36 @@ type. This includes all devices on all instances of that bus type.
 An internal list that the bus uses may be removed, in favor of using
 this one.
 
-The core provides an iterator to access these devices. 
+The core provides an iterator to access these devices::
 
-int bus_for_each_dev(struct bus_type * bus, struct device * start, 
-                     void * data, int (*fn)(struct device *, void *));
+  int bus_for_each_dev(struct bus_type * bus, struct device * start,
+                       void * data, int (*fn)(struct device *, void *));
 
 
 - Driver list.
 
 struct bus_type also contains a list of all drivers registered with
-it. An internal list of drivers that the bus driver maintains may 
-be removed in favor of using the generic one. 
+it. An internal list of drivers that the bus driver maintains may
+be removed in favor of using the generic one.
 
-The drivers may be iterated over, like devices: 
+The drivers may be iterated over, like devices::
 
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
-                     void * data, int (*fn)(struct device_driver *, void *));
+  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+                       void * data, int (*fn)(struct device_driver *, void *));
 
 
 Please see drivers/base/bus.c for more information.
 
 
-- rwsem 
+- rwsem
 
 struct bus_type contains an rwsem that protects all core accesses to
 the device and driver lists. This can be used by the bus driver
 internally, and should be used when accessing the device or driver
-lists the bus maintains. 
+lists the bus maintains.
 
 
-- Device and driver fields. 
+- Device and driver fields.
 
 Some of the fields in struct device and struct device_driver duplicate
 fields in the bus-specific representations of these objects. Feel free
@@ -444,4 +446,3 @@ to remove the bus-specific ones and favor the generic ones. Note
 though, that this will likely mean fixing up all the drivers that
 reference the bus-specific fields (though those should all be 1-line
 changes).
-
diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt
index 2806e5544e43..f388545a85a7 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.txt
@@ -103,7 +103,7 @@ id_table	an array of NULL terminated EISA id strings,
 		(driver_data).
 
 driver		a generic driver, such as described in
-		Documentation/driver-model/driver.txt. Only .name,
+		Documentation/driver-model/driver.rst. Only .name,
 		.probe and .remove members are mandatory.
 =============== ====================================================
 
@@ -152,7 +152,7 @@ state    set of flags indicating the state of the device. Current
 	 flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
 res	 set of four 256 bytes I/O regions allocated to this device
 dma_mask DMA mask set from the parent device.
-dev	 generic device (see Documentation/driver-model/device.txt)
+dev	 generic device (see Documentation/driver-model/device.rst)
 ======== ============================================================
 
 You can get the 'struct eisa_device' from 'struct device' using the
diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst
index f9796b9d9db6..d5b05d3e54ba 100644
--- a/Documentation/hwmon/submitting-patches.rst
+++ b/Documentation/hwmon/submitting-patches.rst
@@ -89,7 +89,7 @@ increase the chances of your change being accepted.
   console. Excessive logging can seriously affect system performance.
 
 * Use devres functions whenever possible to allocate resources. For rationale
-  and supported functions, please see Documentation/driver-model/devres.txt.
+  and supported functions, please see Documentation/driver-model/devres.rst.
   If a function is not supported by devres, consider using devm_add_action().
 
 * If the driver has a detect function, make sure it is silent. Debug messages
diff --git a/drivers/base/platform.c b/drivers/base/platform.c
index dab0a5abc391..f051d22f6e9f 100644
--- a/drivers/base/platform.c
+++ b/drivers/base/platform.c
@@ -5,7 +5,7 @@
  * Copyright (c) 2002-3 Patrick Mochel
  * Copyright (c) 2002-3 Open Source Development Labs
  *
- * Please see Documentation/driver-model/platform.txt for more
+ * Please see Documentation/driver-model/platform.rst for more
  * information.
  */
 
diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c
index 8814c8f47e57..0cb568b3fac9 100644
--- a/drivers/gpio/gpio-cs5535.c
+++ b/drivers/gpio/gpio-cs5535.c
@@ -44,7 +44,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask.");
 
 /*
  * FIXME: convert this singleton driver to use the state container
- * design pattern, see Documentation/driver-model/design-patterns.txt
+ * design pattern, see Documentation/driver-model/design-patterns.rst
  */
 static struct cs5535_gpio_chip {
 	struct gpio_chip chip;
diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c
index f7073e046979..9b627ce970f4 100644
--- a/drivers/net/ethernet/intel/ice/ice_main.c
+++ b/drivers/net/ethernet/intel/ice/ice_main.c
@@ -2220,7 +2220,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent)
 	struct ice_hw *hw;
 	int err;
 
-	/* this driver uses devres, see Documentation/driver-model/devres.txt */
+	/* this driver uses devres, see Documentation/driver-model/devres.rst */
 	err = pcim_enable_device(pdev);
 	if (err)
 		return err;
diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci
index b2a2cf8bf81f..e32236a979a8 100644
--- a/scripts/coccinelle/free/devm_free.cocci
+++ b/scripts/coccinelle/free/devm_free.cocci
@@ -2,7 +2,7 @@
 /// functions.  Values allocated using the devm_functions are freed when
 /// the device is detached, and thus the use of the standard freeing
 /// function would cause a double free.
-/// See Documentation/driver-model/devres.txt for more information.
+/// See Documentation/driver-model/devres.rst for more information.
 ///
 /// A difficulty of detecting this problem is that the standard freeing
 /// function might be called from a different function than the one
-- 
2.20.1

Re: [PATCH v2 48/79] docs: driver-model: convert docs to ReST and rename to *.rst

[Julia Lawall]

> diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci
> index b2a2cf8bf81f..e32236a979a8 100644
> --- a/scripts/coccinelle/free/devm_free.cocci
> +++ b/scripts/coccinelle/free/devm_free.cocci
> @@ -2,7 +2,7 @@
>  /// functions.  Values allocated using the devm_functions are freed when
>  /// the device is detached, and thus the use of the standard freeing
>  /// function would cause a double free.
> -/// See Documentation/driver-model/devres.txt for more information.
> +/// See Documentation/driver-model/devres.rst for more information.
>  ///
>  /// A difficulty of detecting this problem is that the standard freeing
>  /// function might be called from a different function than the one

Acked-by: Julia Lawall <julia.lawall@lip6.fr>



> --
> 2.20.1
>
>

Re: [PATCH v2 48/79] docs: driver-model: convert docs to ReST and rename to *.rst

[Guenter Roeck]

On Mon, Apr 22, 2019 at 10:27:37AM -0300, Mauro Carvalho Chehab wrote:
> Convert the various documents at the driver-model, preparing
> them to be part of the driver-api book.
> 
> The conversion is actually:
>   - add blank lines and identation in order to identify paragraphs;
>   - fix tables markups;
>   - add some lists markups;
>   - mark literal blocks;
>   - adjust title markups.
> 
> 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>
> Acked-by: Julia Lawall <julia.lawall@lip6.fr>
> ---
>  Documentation/driver-api/gpio/driver.rst      |   2 +-
>  .../driver-model/{binding.txt => binding.rst} |  20 +-
>  .../driver-model/{bus.txt => bus.rst}         |  69 ++--
>  .../driver-model/{class.txt => class.rst}     |  74 ++--
>  ...esign-patterns.txt => design-patterns.rst} | 106 +++---
>  .../driver-model/{device.txt => device.rst}   |  57 +--
>  .../driver-model/{devres.txt => devres.rst}   |  50 +--
>  .../driver-model/{driver.txt => driver.rst}   | 112 +++---
>  Documentation/driver-model/index.rst          |  26 ++
>  .../{overview.txt => overview.rst}            |  37 +-
>  .../{platform.txt => platform.rst}            |  30 +-
>  .../driver-model/{porting.txt => porting.rst} | 333 +++++++++---------
>  Documentation/eisa.txt                        |   4 +-
>  Documentation/hwmon/submitting-patches.rst    |   2 +-

For hwmon:

Acked-by: Guenter Roeck <linux@roeck-us.net>

[PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Those files are actually at ReST format. Ok, currently, they
don't belong to any place yet at the organized book series,
but we don't want patches to break them as ReST files. So,
rename them and add a :orphan: in order to shut up warning
messages like those:

...
    Documentation/svga.rst: WARNING: document isn't included in any toctree
    Documentation/switchtec.rst: WARNING: document isn't included in any toctree
...

Later patches will move them to a better place and remove the
:orphan: markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ABI/removed/sysfs-class-rfkill  |  2 +-
 Documentation/ABI/stable/sysfs-class-rfkill   |  2 +-
 Documentation/ABI/stable/sysfs-devices-node   |  2 +-
 Documentation/ABI/testing/procfs-diskstats    |  2 +-
 Documentation/ABI/testing/sysfs-block         |  2 +-
 .../ABI/testing/sysfs-class-switchtec         |  2 +-
 .../ABI/testing/sysfs-devices-system-cpu      |  4 +-
 .../{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst}  |  2 +
 Documentation/{DMA-API.txt => DMA-API.rst}    |  8 ++-
 .../{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst}      |  4 +-
 ...{DMA-attributes.txt => DMA-attributes.rst} |  2 +
 Documentation/{IPMI.txt => IPMI.rst}          |  2 +
 .../{IRQ-affinity.txt => IRQ-affinity.rst}    |  2 +
 .../{IRQ-domain.txt => IRQ-domain.rst}        |  2 +
 Documentation/{IRQ.txt => IRQ.rst}            |  2 +
 .../{Intel-IOMMU.txt => Intel-IOMMU.rst}      |  2 +
 Documentation/PCI/pci.txt                     |  8 +--
 Documentation/{SAK.txt => SAK.rst}            |  2 +
 Documentation/{SM501.txt => SM501.rst}        |  2 +
 .../admin-guide/kernel-parameters.txt         |  6 +-
 Documentation/admin-guide/l1tf.rst            |  2 +-
 .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
 Documentation/block/biodoc.txt                |  2 +-
 .../{bt8xxgpio.txt => bt8xxgpio.rst}          |  2 +
 Documentation/{btmrvl.txt => btmrvl.rst}      |  2 +
 ...-mapping.txt => bus-virt-phys-mapping.rst} |  4 +-
 ...g-warn-once.txt => clearing-warn-once.rst} |  2 +
 Documentation/{cpu-load.txt => cpu-load.rst}  |  2 +
 .../{cputopology.txt => cputopology.rst}      |  2 +
 Documentation/{crc32.txt => crc32.rst}        |  2 +
 Documentation/{dcdbas.txt => dcdbas.rst}      |  2 +
 ...ging-modules.txt => debugging-modules.rst} |  2 +
 ...hci1394.txt => debugging-via-ohci1394.rst} |  2 +
 Documentation/{dell_rbu.txt => dell_rbu.rst}  |  2 +
 Documentation/device-mapper/statistics.rst    |  4 +-
 .../devicetree/bindings/phy/phy-bindings.txt  |  2 +-
 Documentation/{digsig.txt => digsig.rst}      |  2 +
 Documentation/driver-api/usb/dma.rst          |  6 +-
 Documentation/driver-model/device.rst         |  2 +-
 Documentation/{efi-stub.txt => efi-stub.rst}  |  2 +
 Documentation/{eisa.txt => eisa.rst}          |  2 +
 Documentation/fb/vesafb.rst                   |  2 +-
 Documentation/filesystems/sysfs.txt           |  2 +-
 ...ex-requeue-pi.txt => futex-requeue-pi.rst} |  2 +
 .../{gcc-plugins.txt => gcc-plugins.rst}      |  2 +
 Documentation/gpu/drm-mm.rst                  |  2 +-
 Documentation/{highuid.txt => highuid.rst}    |  2 +
 .../{hw_random.txt => hw_random.rst}          |  2 +
 .../{hwspinlock.txt => hwspinlock.rst}        |  2 +
 Documentation/ia64/IRQ-redir.txt              |  2 +-
 .../{intel_txt.txt => intel_txt.rst}          |  2 +
 .../{io-mapping.txt => io-mapping.rst}        |  2 +
 .../{io_ordering.txt => io_ordering.rst}      |  2 +
 Documentation/{iostats.txt => iostats.rst}    |  2 +
 ...flags-tracing.txt => irqflags-tracing.rst} |  2 +
 Documentation/{isa.txt => isa.rst}            |  2 +
 Documentation/{isapnp.txt => isapnp.rst}      |  2 +
 ...hreads.txt => kernel-per-CPU-kthreads.rst} |  4 +-
 Documentation/{kobject.txt => kobject.rst}    |  4 +-
 Documentation/{kprobes.txt => kprobes.rst}    |  2 +
 Documentation/{kref.txt => kref.rst}          |  2 +
 Documentation/laptops/thinkpad-acpi.txt       |  6 +-
 Documentation/{ldm.txt => ldm.rst}            |  2 +
 Documentation/locking/rt-mutex.rst            |  2 +-
 ...kup-watchdogs.txt => lockup-watchdogs.rst} |  2 +
 Documentation/{lsm.txt => lsm.rst}            |  2 +
 Documentation/{lzo.txt => lzo.rst}            |  2 +
 Documentation/{mailbox.txt => mailbox.rst}    |  2 +
 Documentation/memory-barriers.txt             |  6 +-
 ...hameleon-bus.txt => men-chameleon-bus.rst} |  2 +
 Documentation/networking/scaling.rst          |  4 +-
 .../{nommu-mmap.txt => nommu-mmap.rst}        |  2 +
 Documentation/{ntb.txt => ntb.rst}            |  2 +
 Documentation/{numastat.txt => numastat.rst}  |  2 +
 Documentation/{padata.txt => padata.rst}      |  2 +
 ...port-lowlevel.txt => parport-lowlevel.rst} |  2 +
 ...-semaphore.txt => percpu-rw-semaphore.rst} |  2 +
 Documentation/{phy.txt => phy.rst}            |  2 +
 Documentation/{pi-futex.txt => pi-futex.rst}  |  2 +
 Documentation/{pnp.txt => pnp.rst}            |  2 +
 ...reempt-locking.txt => preempt-locking.rst} |  2 +
 Documentation/{pwm.txt => pwm.rst}            |  2 +
 Documentation/{rbtree.txt => rbtree.rst}      |  2 +
 .../{remoteproc.txt => remoteproc.rst}        |  4 +-
 Documentation/{rfkill.txt => rfkill.rst}      |  2 +
 ...ust-futex-ABI.txt => robust-futex-ABI.rst} |  2 +
 ...{robust-futexes.txt => robust-futexes.rst} |  2 +
 Documentation/{rpmsg.txt => rpmsg.rst}        |  2 +
 Documentation/{rtc.txt => rtc.rst}            |  2 +
 Documentation/s390/vfio-ccw.rst               |  6 +-
 Documentation/{sgi-ioc4.txt => sgi-ioc4.rst}  |  2 +
 Documentation/{siphash.txt => siphash.rst}    |  2 +
 .../{smsc_ece1099.txt => smsc_ece1099.rst}    |  2 +
 .../{speculation.txt => speculation.rst}      |  2 +
 .../{static-keys.txt => static-keys.rst}      |  2 +
 Documentation/{svga.txt => svga.rst}          |  2 +
 .../{switchtec.txt => switchtec.rst}          |  4 +-
 .../{sync_file.txt => sync_file.rst}          |  2 +
 Documentation/sysctl/kernel.txt               |  4 +-
 Documentation/sysctl/vm.txt                   |  2 +-
 Documentation/{tee.txt => tee.rst}            |  2 +
 .../{this_cpu_ops.txt => this_cpu_ops.rst}    |  2 +
 Documentation/trace/kprobetrace.rst           |  2 +-
 .../translations/ko_KR/memory-barriers.txt    |  6 +-
 Documentation/translations/zh_CN/IRQ.txt      |  4 +-
 .../translations/zh_CN/filesystems/sysfs.txt  |  2 +-
 .../translations/zh_CN/io_ordering.txt        |  4 +-
 ...access.txt => unaligned-memory-access.rst} |  2 +
 ...ed-device.txt => vfio-mediated-device.rst} |  4 +-
 Documentation/{vfio.txt => vfio.rst}          |  2 +
 .../{video-output.txt => video-output.rst}    |  2 +
 Documentation/watchdog/hpwdt.rst              |  2 +-
 Documentation/x86/topology.txt                |  2 +-
 Documentation/{xillybus.txt => xillybus.rst}  |  2 +
 Documentation/{xz.txt => xz.rst}              |  2 +
 Documentation/{zorro.txt => zorro.rst}        |  2 +
 MAINTAINERS                                   | 56 +++++++++----------
 arch/Kconfig                                  |  4 +-
 arch/arm/Kconfig                              |  4 +-
 arch/ia64/hp/common/sba_iommu.c               | 12 ++--
 arch/ia64/sn/pci/pci_dma.c                    |  4 +-
 arch/parisc/Kconfig                           |  2 +-
 arch/parisc/kernel/pci-dma.c                  |  2 +-
 arch/sh/Kconfig                               |  2 +-
 arch/sparc/Kconfig                            |  2 +-
 arch/unicore32/include/asm/io.h               |  2 +-
 arch/x86/Kconfig                              |  4 +-
 arch/x86/include/asm/dma-mapping.h            |  4 +-
 arch/x86/kernel/amd_gart_64.c                 |  2 +-
 block/partitions/Kconfig                      |  2 +-
 drivers/base/core.c                           |  2 +-
 drivers/char/Kconfig                          |  4 +-
 drivers/char/hw_random/core.c                 |  2 +-
 drivers/char/ipmi/Kconfig                     |  2 +-
 drivers/char/ipmi/ipmi_si_hotmod.c            |  2 +-
 drivers/char/ipmi/ipmi_si_intf.c              |  2 +-
 drivers/dma-buf/Kconfig                       |  2 +-
 drivers/gpio/Kconfig                          |  2 +-
 drivers/parisc/sba_iommu.c                    | 16 +++---
 drivers/pci/switch/Kconfig                    |  2 +-
 drivers/platform/x86/Kconfig                  |  4 +-
 drivers/platform/x86/dcdbas.c                 |  2 +-
 drivers/platform/x86/dell_rbu.c               |  2 +-
 drivers/pnp/isapnp/Kconfig                    |  2 +-
 drivers/vfio/Kconfig                          |  2 +-
 drivers/vfio/mdev/Kconfig                     |  2 +-
 include/asm-generic/bitops/atomic.h           |  2 +-
 include/linux/dma-mapping.h                   |  2 +-
 include/linux/hw_random.h                     |  2 +-
 include/linux/io-mapping.h                    |  2 +-
 include/linux/jump_label.h                    |  2 +-
 include/linux/kobject.h                       |  2 +-
 include/linux/kobject_ns.h                    |  2 +-
 include/linux/rbtree.h                        |  2 +-
 include/linux/rbtree_augmented.h              |  2 +-
 include/media/videobuf-dma-sg.h               |  2 +-
 init/Kconfig                                  |  2 +-
 kernel/dma/debug.c                            |  2 +-
 kernel/padata.c                               |  2 +-
 lib/Kconfig                                   |  2 +-
 lib/Kconfig.debug                             |  2 +-
 lib/crc32.c                                   |  2 +-
 lib/kobject.c                                 |  4 +-
 lib/lzo/lzo1x_decompress_safe.c               |  2 +-
 lib/xz/Kconfig                                |  2 +-
 mm/Kconfig                                    |  2 +-
 mm/nommu.c                                    |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 scripts/gcc-plugins/Kconfig                   |  2 +-
 security/Kconfig                              |  2 +-
 tools/include/linux/rbtree.h                  |  2 +-
 tools/include/linux/rbtree_augmented.h        |  2 +-
 173 files changed, 334 insertions(+), 168 deletions(-)
 rename Documentation/{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst} (99%)
 rename Documentation/{DMA-API.txt => DMA-API.rst} (99%)
 rename Documentation/{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst} (98%)
 rename Documentation/{DMA-attributes.txt => DMA-attributes.rst} (99%)
 rename Documentation/{IPMI.txt => IPMI.rst} (99%)
 rename Documentation/{IRQ-affinity.txt => IRQ-affinity.rst} (99%)
 rename Documentation/{IRQ-domain.txt => IRQ-domain.rst} (99%)
 rename Documentation/{IRQ.txt => IRQ.rst} (99%)
 rename Documentation/{Intel-IOMMU.txt => Intel-IOMMU.rst} (99%)
 rename Documentation/{SAK.txt => SAK.rst} (99%)
 rename Documentation/{SM501.txt => SM501.rst} (99%)
 rename Documentation/{atomic_bitops.txt => atomic_bitops.rst} (99%)
 rename Documentation/{bt8xxgpio.txt => bt8xxgpio.rst} (99%)
 rename Documentation/{btmrvl.txt => btmrvl.rst} (99%)
 rename Documentation/{bus-virt-phys-mapping.txt => bus-virt-phys-mapping.rst} (99%)
 rename Documentation/{clearing-warn-once.txt => clearing-warn-once.rst} (96%)
 rename Documentation/{cpu-load.txt => cpu-load.rst} (99%)
 rename Documentation/{cputopology.txt => cputopology.rst} (99%)
 rename Documentation/{crc32.txt => crc32.rst} (99%)
 rename Documentation/{dcdbas.txt => dcdbas.rst} (99%)
 rename Documentation/{debugging-modules.txt => debugging-modules.rst} (98%)
 rename Documentation/{debugging-via-ohci1394.txt => debugging-via-ohci1394.rst} (99%)
 rename Documentation/{dell_rbu.txt => dell_rbu.rst} (99%)
 rename Documentation/{digsig.txt => digsig.rst} (99%)
 rename Documentation/{efi-stub.txt => efi-stub.rst} (99%)
 rename Documentation/{eisa.txt => eisa.rst} (99%)
 rename Documentation/{futex-requeue-pi.txt => futex-requeue-pi.rst} (99%)
 rename Documentation/{gcc-plugins.txt => gcc-plugins.rst} (99%)
 rename Documentation/{highuid.txt => highuid.rst} (99%)
 rename Documentation/{hw_random.txt => hw_random.rst} (99%)
 rename Documentation/{hwspinlock.txt => hwspinlock.rst} (99%)
 rename Documentation/{intel_txt.txt => intel_txt.rst} (99%)
 rename Documentation/{io-mapping.txt => io-mapping.rst} (99%)
 rename Documentation/{io_ordering.txt => io_ordering.rst} (99%)
 rename Documentation/{iostats.txt => iostats.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => irqflags-tracing.rst} (99%)
 rename Documentation/{isa.txt => isa.rst} (99%)
 rename Documentation/{isapnp.txt => isapnp.rst} (98%)
 rename Documentation/{kernel-per-CPU-kthreads.txt => kernel-per-CPU-kthreads.rst} (99%)
 rename Documentation/{kobject.txt => kobject.rst} (99%)
 rename Documentation/{kprobes.txt => kprobes.rst} (99%)
 rename Documentation/{kref.txt => kref.rst} (99%)
 rename Documentation/{ldm.txt => ldm.rst} (99%)
 rename Documentation/{lockup-watchdogs.txt => lockup-watchdogs.rst} (99%)
 rename Documentation/{lsm.txt => lsm.rst} (99%)
 rename Documentation/{lzo.txt => lzo.rst} (99%)
 rename Documentation/{mailbox.txt => mailbox.rst} (99%)
 rename Documentation/{men-chameleon-bus.txt => men-chameleon-bus.rst} (99%)
 rename Documentation/{nommu-mmap.txt => nommu-mmap.rst} (99%)
 rename Documentation/{ntb.txt => ntb.rst} (99%)
 rename Documentation/{numastat.txt => numastat.rst} (99%)
 rename Documentation/{padata.txt => padata.rst} (99%)
 rename Documentation/{parport-lowlevel.txt => parport-lowlevel.rst} (99%)
 rename Documentation/{percpu-rw-semaphore.txt => percpu-rw-semaphore.rst} (99%)
 rename Documentation/{phy.txt => phy.rst} (99%)
 rename Documentation/{pi-futex.txt => pi-futex.rst} (99%)
 rename Documentation/{pnp.txt => pnp.rst} (99%)
 rename Documentation/{preempt-locking.txt => preempt-locking.rst} (99%)
 rename Documentation/{pwm.txt => pwm.rst} (99%)
 rename Documentation/{rbtree.txt => rbtree.rst} (99%)
 rename Documentation/{remoteproc.txt => remoteproc.rst} (99%)
 rename Documentation/{rfkill.txt => rfkill.rst} (99%)
 rename Documentation/{robust-futex-ABI.txt => robust-futex-ABI.rst} (99%)
 rename Documentation/{robust-futexes.txt => robust-futexes.rst} (99%)
 rename Documentation/{rpmsg.txt => rpmsg.rst} (99%)
 rename Documentation/{rtc.txt => rtc.rst} (99%)
 rename Documentation/{sgi-ioc4.txt => sgi-ioc4.rst} (99%)
 rename Documentation/{siphash.txt => siphash.rst} (99%)
 rename Documentation/{smsc_ece1099.txt => smsc_ece1099.rst} (99%)
 rename Documentation/{speculation.txt => speculation.rst} (99%)
 rename Documentation/{static-keys.txt => static-keys.rst} (99%)
 rename Documentation/{svga.txt => svga.rst} (99%)
 rename Documentation/{switchtec.txt => switchtec.rst} (98%)
 rename Documentation/{sync_file.txt => sync_file.rst} (99%)
 rename Documentation/{tee.txt => tee.rst} (99%)
 rename Documentation/{this_cpu_ops.txt => this_cpu_ops.rst} (99%)
 rename Documentation/{unaligned-memory-access.txt => unaligned-memory-access.rst} (99%)
 rename Documentation/{vfio-mediated-device.txt => vfio-mediated-device.rst} (99%)
 rename Documentation/{vfio.txt => vfio.rst} (99%)
 rename Documentation/{video-output.txt => video-output.rst} (99%)
 rename Documentation/{xillybus.txt => xillybus.rst} (99%)
 rename Documentation/{xz.txt => xz.rst} (99%)
 rename Documentation/{zorro.txt => zorro.rst} (99%)

diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill
index 3ce6231f20b2..1652b2381dda 100644
--- a/Documentation/ABI/removed/sysfs-class-rfkill
+++ b/Documentation/ABI/removed/sysfs-class-rfkill
@@ -1,6 +1,6 @@
 rfkill - radio frequency (RF) connector kill switch support
 
-For details to this subsystem look at Documentation/rfkill.txt.
+For details to this subsystem look at Documentation/rfkill.rst.
 
 What:		/sys/class/rfkill/rfkill[0-9]+/claim
 Date:		09-Jul-2007
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 80151a409d67..68fd0afdad0d 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -1,6 +1,6 @@
 rfkill - radio frequency (RF) connector kill switch support
 
-For details to this subsystem look at Documentation/rfkill.txt.
+For details to this subsystem look at Documentation/rfkill.rst.
 
 For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
 Documentation/ABI/removed/sysfs-class-rfkill.
diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node
index f7ce68fbd4b9..de1d022c0864 100644
--- a/Documentation/ABI/stable/sysfs-devices-node
+++ b/Documentation/ABI/stable/sysfs-devices-node
@@ -61,7 +61,7 @@ Date:		October 2002
 Contact:	Linux Memory Management list <linux-mm@kvack.org>
 Description:
 		The node's hit/miss statistics, in units of pages.
-		See Documentation/numastat.txt
+		See Documentation/numastat.rst
 
 What:		/sys/devices/system/node/nodeX/distance
 Date:		October 2002
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index abac31d216de..26661dd5188b 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -29,4 +29,4 @@ Description:
 		17 - sectors discarded
 		18 - time spent discarding
 
-		For more details refer to Documentation/iostats.txt
+		For more details refer to Documentation/iostats.rst
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index dfad7427817c..d300a6b9d17c 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -15,7 +15,7 @@ Description:
 		 9 - I/Os currently in progress
 		10 - time spent doing I/Os (ms)
 		11 - weighted time spent doing I/Os (ms)
-		For more details refer Documentation/iostats.txt
+		For more details refer Documentation/iostats.rst
 
 
 What:		/sys/block/<disk>/<part>/stat
diff --git a/Documentation/ABI/testing/sysfs-class-switchtec b/Documentation/ABI/testing/sysfs-class-switchtec
index 48cb4c15e430..c8d80db1e32c 100644
--- a/Documentation/ABI/testing/sysfs-class-switchtec
+++ b/Documentation/ABI/testing/sysfs-class-switchtec
@@ -1,6 +1,6 @@
 switchtec - Microsemi Switchtec PCI Switch Management Endpoint
 
-For details on this subsystem look at Documentation/switchtec.txt.
+For details on this subsystem look at Documentation/switchtec.rst.
 
 What: 		/sys/class/switchtec
 Date:		05-Jan-2017
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 4fb76c0e8d30..4ee760342c62 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -34,7 +34,7 @@ Description:	CPU topology files that describe kernel limits related to
 		present: cpus that have been identified as being present in
 		the system.
 
-		See Documentation/cputopology.txt for more information.
+		See Documentation/cputopology.rst for more information.
 
 
 What:		/sys/devices/system/cpu/probe
@@ -103,7 +103,7 @@ Description:	CPU topology files that describe a logical CPU's relationship
 		thread_siblings_list: human-readable list of cpu#'s hardware
 		threads within the same core as cpu#
 
-		See Documentation/cputopology.txt for more information.
+		See Documentation/cputopology.rst for more information.
 
 
 What:		/sys/devices/system/cpu/cpuidle/current_driver
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.rst
similarity index 99%
rename from Documentation/DMA-API-HOWTO.txt
rename to Documentation/DMA-API-HOWTO.rst
index cb712a02f59f..0b72bf9051ed 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 Dynamic DMA mapping Guide
 =========================
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.rst
similarity index 99%
rename from Documentation/DMA-API.txt
rename to Documentation/DMA-API.rst
index 0076150fdccb..ede74c6ae87d 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================================
 Dynamic DMA mapping using the generic device
 ============================================
@@ -5,7 +7,7 @@ Dynamic DMA mapping using the generic device
 :Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
 
 This document describes the DMA API.  For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
+of the API (and actual examples), see Documentation/DMA-API-HOWTO.rst.
 
 This API is split into two pieces.  Part I describes the basic API.
 Part II describes extensions for supporting non-consistent memory
@@ -463,7 +465,7 @@ without the _attrs suffixes, except that they pass an optional
 dma_attrs.
 
 The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
+each attribute should be documented in Documentation/DMA-attributes.rst.
 
 If dma_attrs are 0, the semantics of each of these functions
 is identical to those of the corresponding function
@@ -476,7 +478,7 @@ for DMA::
 
 	#include <linux/dma-mapping.h>
 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
-	* documented in Documentation/DMA-attributes.txt */
+	* documented in Documentation/DMA-attributes.rst */
 	...
 
 		unsigned long attr;
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.rst
similarity index 98%
rename from Documentation/DMA-ISA-LPC.txt
rename to Documentation/DMA-ISA-LPC.rst
index b1ec7b16c21f..205a379c2d62 100644
--- a/Documentation/DMA-ISA-LPC.txt
+++ b/Documentation/DMA-ISA-LPC.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 DMA with ISA and LPC devices
 ============================
@@ -17,7 +19,7 @@ To do ISA style DMA you need to include two headers::
 	#include <asm/dma.h>
 
 The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
+bus addresses (see Documentation/DMA-API.rst for details).
 
 The second contains the routines specific to ISA DMA transfers. Since
 this is not present on all platforms make sure you construct your
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.rst
similarity index 99%
rename from Documentation/DMA-attributes.txt
rename to Documentation/DMA-attributes.rst
index 8f8d97f65d73..471c5c38f9d9 100644
--- a/Documentation/DMA-attributes.txt
+++ b/Documentation/DMA-attributes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==============
 DMA attributes
 ==============
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.rst
similarity index 99%
rename from Documentation/IPMI.txt
rename to Documentation/IPMI.rst
index 5ef1047e2e66..f6c2d11710fe 100644
--- a/Documentation/IPMI.txt
+++ b/Documentation/IPMI.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 The Linux IPMI Driver
 =====================
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/IRQ-affinity.rst
similarity index 99%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/IRQ-affinity.rst
index 29da5000836a..49ba271349d6 100644
--- a/Documentation/IRQ-affinity.txt
+++ b/Documentation/IRQ-affinity.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 SMP IRQ affinity
 ================
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.rst
similarity index 99%
rename from Documentation/IRQ-domain.txt
rename to Documentation/IRQ-domain.rst
index 507775cce753..a610a8ea9a92 100644
--- a/Documentation/IRQ-domain.txt
+++ b/Documentation/IRQ-domain.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================================
 The irq_domain interrupt number mapping library
 ===============================================
diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.rst
similarity index 99%
rename from Documentation/IRQ.txt
rename to Documentation/IRQ.rst
index 4273806a606b..a9f3e192c2cb 100644
--- a/Documentation/IRQ.txt
+++ b/Documentation/IRQ.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============
 What is an IRQ?
 ===============
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.rst
similarity index 99%
rename from Documentation/Intel-IOMMU.txt
rename to Documentation/Intel-IOMMU.rst
index 9dae6b47e398..b001104c25c8 100644
--- a/Documentation/Intel-IOMMU.txt
+++ b/Documentation/Intel-IOMMU.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 Linux IOMMU Support
 ===================
diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt
index bbbae19f10b0..8f0009b6ea1d 100644
--- a/Documentation/PCI/pci.txt
+++ b/Documentation/PCI/pci.txt
@@ -295,7 +295,7 @@ from the PCI device config space. Use the values in the pci_dev structure
 as the PCI "bus address" might have been remapped to a "host physical"
 address by the arch/chip-set specific kernel support.
 
-See Documentation/io-mapping.txt for how to access device registers
+See Documentation/io-mapping.rst for how to access device registers
 or device memory.
 
 The device driver needs to call pci_request_region() to verify
@@ -319,7 +319,7 @@ Also see pci_request_selected_regions() below.
 3.3 Set the DMA mask size
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 [ If anything below doesn't make sense, please refer to
-  Documentation/DMA-API.txt. This section is just a reminder that
+  Documentation/DMA-API.rst. This section is just a reminder that
   drivers need to indicate DMA capabilities of the device and is not
   an authoritative source for DMA interfaces. ]
 
@@ -345,7 +345,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 3.4 Setup shared control data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory.  See Documentation/DMA-API.txt for a full description of
+memory.  See Documentation/DMA-API.rst for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
 before enabling DMA on the device.
 
@@ -475,7 +475,7 @@ owners if there is one.
 
 Then clean up "consistent" buffers which contain the control data.
 
-See Documentation/DMA-API.txt for details on unmapping interfaces.
+See Documentation/DMA-API.rst for details on unmapping interfaces.
 
 
 4.5 Unregister from other subsystems
diff --git a/Documentation/SAK.txt b/Documentation/SAK.rst
similarity index 99%
rename from Documentation/SAK.txt
rename to Documentation/SAK.rst
index 260e1d3687bd..c6fe715f5518 100644
--- a/Documentation/SAK.txt
+++ b/Documentation/SAK.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================================
 Linux Secure Attention Key (SAK) handling
 =========================================
diff --git a/Documentation/SM501.txt b/Documentation/SM501.rst
similarity index 99%
rename from Documentation/SM501.txt
rename to Documentation/SM501.rst
index 882507453ba4..772a9b5c7d49 100644
--- a/Documentation/SM501.txt
+++ b/Documentation/SM501.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 ============
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 4a2260eac131..bf6d34fb7180 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3077,7 +3077,7 @@
 			See Documentation/sysctl/vm.txt for details.
 
 	ohci1394_dma=early	[HW] enable debugging via the ohci1394 driver.
-			See Documentation/debugging-via-ohci1394.txt for more
+			See Documentation/debugging-via-ohci1394.rst for more
 			info.
 
 	olpc_ec_timeout= [OLPC] ms delay when issuing EC commands
@@ -4986,8 +4986,8 @@
 			Can be used multiple times for multiple devices.
 
 	vga=		[BOOT,X86-32] Select a particular video mode
-			See Documentation/x86/boot.txt and
-			Documentation/svga.txt.
+			See Documentation/x86/boot.rst and
+			Documentation/svga.rst.
 			Use vga=ask for menu.
 			This is actually a boot loader parameter; the value is
 			passed to the kernel using a special protocol.
diff --git a/Documentation/admin-guide/l1tf.rst b/Documentation/admin-guide/l1tf.rst
index f5b2a54a0dc2..ab162d65e178 100644
--- a/Documentation/admin-guide/l1tf.rst
+++ b/Documentation/admin-guide/l1tf.rst
@@ -268,7 +268,7 @@ Guest mitigation mechanisms
    /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
    available at:
 
-   https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
+   https://www.kernel.org/doc/Documentation/IRQ-affinity.rst
 
 .. _smt_control:
 
diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.rst
similarity index 99%
rename from Documentation/atomic_bitops.txt
rename to Documentation/atomic_bitops.rst
index 093cdaefdb37..ca90f2d16602 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 Atomic bitops
 =============
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt
index ac18b488cb5e..ac504de0cb93 100644
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.txt
@@ -184,7 +184,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
 do not have a corresponding kernel virtual address space mapping) and
 low-memory pages.
 
-Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
+Note: Please refer to Documentation/DMA-API-HOWTO.rst for a discussion
 on PCI high mem DMA aspects and mapping of scatter gather lists, and support
 for 64 bit PCI.
 
diff --git a/Documentation/bt8xxgpio.txt b/Documentation/bt8xxgpio.rst
similarity index 99%
rename from Documentation/bt8xxgpio.txt
rename to Documentation/bt8xxgpio.rst
index a845feb074de..efda63a77f18 100644
--- a/Documentation/bt8xxgpio.txt
+++ b/Documentation/bt8xxgpio.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================================
 A driver for a selfmade cheap BT8xx based PCI GPIO-card (bt8xxgpio)
 ===================================================================
diff --git a/Documentation/btmrvl.txt b/Documentation/btmrvl.rst
similarity index 99%
rename from Documentation/btmrvl.txt
rename to Documentation/btmrvl.rst
index ec57740ead0c..e6dd1c96e842 100644
--- a/Documentation/btmrvl.txt
+++ b/Documentation/btmrvl.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 btmrvl driver
 =============
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.rst
similarity index 99%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/bus-virt-phys-mapping.rst
index 4bb07c2f3e7d..0f22390b980a 100644
--- a/Documentation/bus-virt-phys-mapping.txt
+++ b/Documentation/bus-virt-phys-mapping.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 How to access I/O mapped memory from within device drivers
 ==========================================================
@@ -8,7 +10,7 @@ How to access I/O mapped memory from within device drivers
 
 	The virt_to_bus() and bus_to_virt() functions have been
 	superseded by the functionality provided by the PCI DMA interface
-	(see Documentation/DMA-API-HOWTO.txt).  They continue
+	(see Documentation/DMA-API-HOWTO.rst).  They continue
 	to be documented below for historical purposes, but new code
 	must not use them. --davidm 00/12/12
 
diff --git a/Documentation/clearing-warn-once.txt b/Documentation/clearing-warn-once.rst
similarity index 96%
rename from Documentation/clearing-warn-once.txt
rename to Documentation/clearing-warn-once.rst
index 211fd926cf00..cdfa892c7fdf 100644
--- a/Documentation/clearing-warn-once.txt
+++ b/Documentation/clearing-warn-once.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Clearing WARN_ONCE
 ------------------
 
diff --git a/Documentation/cpu-load.txt b/Documentation/cpu-load.rst
similarity index 99%
rename from Documentation/cpu-load.txt
rename to Documentation/cpu-load.rst
index 2d01ce43d2a2..6b2815b78683 100644
--- a/Documentation/cpu-load.txt
+++ b/Documentation/cpu-load.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========
 CPU load
 ========
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.rst
similarity index 99%
rename from Documentation/cputopology.txt
rename to Documentation/cputopology.rst
index c6e7e9196a8b..cce9cedd2996 100644
--- a/Documentation/cputopology.txt
+++ b/Documentation/cputopology.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================
 How CPU topology info is exported via sysfs
 ===========================================
diff --git a/Documentation/crc32.txt b/Documentation/crc32.rst
similarity index 99%
rename from Documentation/crc32.txt
rename to Documentation/crc32.rst
index 8a6860f33b4e..f7c73d713a35 100644
--- a/Documentation/crc32.txt
+++ b/Documentation/crc32.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 brief tutorial on CRC computation
 =================================
diff --git a/Documentation/dcdbas.txt b/Documentation/dcdbas.rst
similarity index 99%
rename from Documentation/dcdbas.txt
rename to Documentation/dcdbas.rst
index 309cc57a7c1c..abbc2bfd58a7 100644
--- a/Documentation/dcdbas.txt
+++ b/Documentation/dcdbas.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================
 Dell Systems Management Base Driver
 ===================================
diff --git a/Documentation/debugging-modules.txt b/Documentation/debugging-modules.rst
similarity index 98%
rename from Documentation/debugging-modules.txt
rename to Documentation/debugging-modules.rst
index 172ad4aec493..994f4b021a81 100644
--- a/Documentation/debugging-modules.txt
+++ b/Documentation/debugging-modules.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Debugging Modules after 2.6.3
 -----------------------------
 
diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.rst
similarity index 99%
rename from Documentation/debugging-via-ohci1394.txt
rename to Documentation/debugging-via-ohci1394.rst
index 981ad4f89fd3..ead0196d94b7 100644
--- a/Documentation/debugging-via-ohci1394.txt
+++ b/Documentation/debugging-via-ohci1394.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================================
 Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
 ===========================================================================
diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.rst
similarity index 99%
rename from Documentation/dell_rbu.txt
rename to Documentation/dell_rbu.rst
index 5d1ce7bcd04d..1104726616a1 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============================================================
 Usage of the new open sourced rbu (Remote BIOS Update) driver
 =============================================================
diff --git a/Documentation/device-mapper/statistics.rst b/Documentation/device-mapper/statistics.rst
index 3d80a9f850cc..39f74af35abb 100644
--- a/Documentation/device-mapper/statistics.rst
+++ b/Documentation/device-mapper/statistics.rst
@@ -13,7 +13,7 @@ the range specified.
 
 The I/O statistics counters for each step-sized area of a region are
 in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
-Documentation/iostats.txt).  But two extra counters (12 and 13) are
+Documentation/iostats.rst).  But two extra counters (12 and 13) are
 provided: total time spent reading and writing.  When the histogram
 argument is used, the 14th parameter is reported that represents the
 histogram of latencies.  All these counters may be accessed by sending
@@ -151,7 +151,7 @@ Messages
 	  The first 11 counters have the same meaning as
 	  `/sys/block/*/stat or /proc/diskstats`.
 
-	  Please refer to Documentation/iostats.txt for details.
+	  Please refer to Documentation/iostats.rst for details.
 
 	  1. the number of reads completed
 	  2. the number of reads merged
diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.txt b/Documentation/devicetree/bindings/phy/phy-bindings.txt
index a403b81d0679..5e2a53bcba0e 100644
--- a/Documentation/devicetree/bindings/phy/phy-bindings.txt
+++ b/Documentation/devicetree/bindings/phy/phy-bindings.txt
@@ -1,5 +1,5 @@
 This document explains only the device tree data binding. For general
-information about PHY subsystem refer to Documentation/phy.txt
+information about PHY subsystem refer to Documentation/phy.rst
 
 PHY device node
 ===============
diff --git a/Documentation/digsig.txt b/Documentation/digsig.rst
similarity index 99%
rename from Documentation/digsig.txt
rename to Documentation/digsig.rst
index f6a8902d3ef7..3597711d0df1 100644
--- a/Documentation/digsig.txt
+++ b/Documentation/digsig.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==================================
 Digital Signature Verification API
 ==================================
diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
index 59d5aee89e37..12955a77c7fe 100644
--- a/Documentation/driver-api/usb/dma.rst
+++ b/Documentation/driver-api/usb/dma.rst
@@ -10,7 +10,7 @@ API overview
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+``Documentation/DMA-API-HOWTO.rst``).  That's how they've worked through
 the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
 DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.rst`` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
+of Documentation/DMA-API-HOWTO.rst, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-model/device.rst
index 2b868d49d349..17bcc483c4b1 100644
--- a/Documentation/driver-model/device.rst
+++ b/Documentation/driver-model/device.rst
@@ -53,7 +53,7 @@ Attributes of devices can be exported by a device driver through sysfs.
 Please see Documentation/filesystems/sysfs.txt for more information
 on how sysfs works.
 
-As explained in Documentation/kobject.txt, device attributes must be
+As explained in Documentation/kobject.rst, device attributes must be
 created before the KOBJ_ADD uevent is generated. The only way to realize
 that is by defining an attribute group.
 
diff --git a/Documentation/efi-stub.txt b/Documentation/efi-stub.rst
similarity index 99%
rename from Documentation/efi-stub.txt
rename to Documentation/efi-stub.rst
index 833edb0d0bc4..29256cad8af3 100644
--- a/Documentation/efi-stub.txt
+++ b/Documentation/efi-stub.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 The EFI Boot Stub
 =================
diff --git a/Documentation/eisa.txt b/Documentation/eisa.rst
similarity index 99%
rename from Documentation/eisa.txt
rename to Documentation/eisa.rst
index f388545a85a7..d98949908405 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 EISA bus support
 ================
diff --git a/Documentation/fb/vesafb.rst b/Documentation/fb/vesafb.rst
index 2ed0dfb661cf..a0b658091b07 100644
--- a/Documentation/fb/vesafb.rst
+++ b/Documentation/fb/vesafb.rst
@@ -30,7 +30,7 @@ How to use it?
 ==============
 
 Switching modes is done using the vga=... boot parameter.  Read
-Documentation/svga.txt for details.
+Documentation/svga.rst for details.
 
 You should compile in both vgacon (for text mode) and vesafb (for
 graphics mode). Which of them takes over the console depends on
diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt
index 5b5311f9358d..d159826c5cf3 100644
--- a/Documentation/filesystems/sysfs.txt
+++ b/Documentation/filesystems/sysfs.txt
@@ -16,7 +16,7 @@ a means to export kernel data structures, their attributes, and the
 linkages between them to userspace. 
 
 sysfs is tied inherently to the kobject infrastructure. Please read
-Documentation/kobject.txt for more information concerning the kobject
+Documentation/kobject.rst for more information concerning the kobject
 interface. 
 
 
diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.rst
similarity index 99%
rename from Documentation/futex-requeue-pi.txt
rename to Documentation/futex-requeue-pi.rst
index 14ab5787b9a7..a90dbff26629 100644
--- a/Documentation/futex-requeue-pi.txt
+++ b/Documentation/futex-requeue-pi.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 Futex Requeue PI
 ================
diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.rst
similarity index 99%
rename from Documentation/gcc-plugins.txt
rename to Documentation/gcc-plugins.rst
index 8502f24396fb..e08d013c6de2 100644
--- a/Documentation/gcc-plugins.txt
+++ b/Documentation/gcc-plugins.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 GCC plugin infrastructure
 =========================
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 54a696d961a7..adadaf796dce 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -321,7 +321,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
 field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
 
 More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/nommu-mmap.rst
 
 Memory Coherency
 ----------------
diff --git a/Documentation/highuid.txt b/Documentation/highuid.rst
similarity index 99%
rename from Documentation/highuid.txt
rename to Documentation/highuid.rst
index 6ee70465c0ea..f2fcf729f64c 100644
--- a/Documentation/highuid.txt
+++ b/Documentation/highuid.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================
 Notes on the change from 16-bit UIDs to 32-bit UIDs
 ===================================================
diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.rst
similarity index 99%
rename from Documentation/hw_random.txt
rename to Documentation/hw_random.rst
index 121de96e395e..fb5e32fae384 100644
--- a/Documentation/hw_random.txt
+++ b/Documentation/hw_random.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 Linux support for random number generator in i8xx chipsets
 ==========================================================
diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.rst
similarity index 99%
rename from Documentation/hwspinlock.txt
rename to Documentation/hwspinlock.rst
index ed640a278185..68297473647c 100644
--- a/Documentation/hwspinlock.txt
+++ b/Documentation/hwspinlock.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================
 Hardware Spinlock Framework
 ===========================
diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/IRQ-redir.txt
index f7bd72261283..364ce9879f54 100644
--- a/Documentation/ia64/IRQ-redir.txt
+++ b/Documentation/ia64/IRQ-redir.txt
@@ -5,7 +5,7 @@ IRQ affinity on IA64 platforms
 
 By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
 controlled. The behavior on IA64 platforms is slightly different from
-that described in Documentation/IRQ-affinity.txt for i386 systems.
+that described in Documentation/IRQ-affinity.rst for i386 systems.
 
 Because of the usage of SAPIC mode and physical destination mode the
 IRQ target is one particular CPU and cannot be a mask of several
diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.rst
similarity index 99%
rename from Documentation/intel_txt.txt
rename to Documentation/intel_txt.rst
index d83c1a2122c9..5a55007ecf08 100644
--- a/Documentation/intel_txt.txt
+++ b/Documentation/intel_txt.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 Intel(R) TXT Overview
 =====================
diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.rst
similarity index 99%
rename from Documentation/io-mapping.txt
rename to Documentation/io-mapping.rst
index a966239f04e4..82a2cacf9a29 100644
--- a/Documentation/io-mapping.txt
+++ b/Documentation/io-mapping.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================
 The io_mapping functions
 ========================
diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.rst
similarity index 99%
rename from Documentation/io_ordering.txt
rename to Documentation/io_ordering.rst
index 2ab303ce9a0d..18ef889c100e 100644
--- a/Documentation/io_ordering.txt
+++ b/Documentation/io_ordering.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==============================================
 Ordering I/O writes to memory-mapped addresses
 ==============================================
diff --git a/Documentation/iostats.txt b/Documentation/iostats.rst
similarity index 99%
rename from Documentation/iostats.txt
rename to Documentation/iostats.rst
index 49df45f90e8a..d2489cb8e1b3 100644
--- a/Documentation/iostats.txt
+++ b/Documentation/iostats.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 I/O statistics fields
 =====================
diff --git a/Documentation/irqflags-tracing.txt b/Documentation/irqflags-tracing.rst
similarity index 99%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/irqflags-tracing.rst
index bdd208259fb3..b9c2acd5e835 100644
--- a/Documentation/irqflags-tracing.txt
+++ b/Documentation/irqflags-tracing.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================
 IRQ-flags state tracing
 =======================
diff --git a/Documentation/isa.txt b/Documentation/isa.rst
similarity index 99%
rename from Documentation/isa.txt
rename to Documentation/isa.rst
index def4a7b690b5..f3a412d266b0 100644
--- a/Documentation/isa.txt
+++ b/Documentation/isa.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 ISA Drivers
 ===========
diff --git a/Documentation/isapnp.txt b/Documentation/isapnp.rst
similarity index 98%
rename from Documentation/isapnp.txt
rename to Documentation/isapnp.rst
index 8d0840ac847b..136a5e92be27 100644
--- a/Documentation/isapnp.txt
+++ b/Documentation/isapnp.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz>
 ==========================================================
diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.rst
similarity index 99%
rename from Documentation/kernel-per-CPU-kthreads.txt
rename to Documentation/kernel-per-CPU-kthreads.rst
index 5623b9916411..765c7b9bd7fd 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 Reducing OS jitter due to per-cpu kthreads
 ==========================================
@@ -10,7 +12,7 @@ them to a "housekeeping" CPU dedicated to such work.
 References
 ==========
 
--	Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
+-	Documentation/IRQ-affinity.rst:  Binding interrupts to sets of CPUs.
 
 -	Documentation/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
 
diff --git a/Documentation/kobject.txt b/Documentation/kobject.rst
similarity index 99%
rename from Documentation/kobject.txt
rename to Documentation/kobject.rst
index ff4c25098119..09cd1fc3e9e0 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================================================================
 Everything you never wanted to know about kobjects, ksets, and ktypes
 =====================================================================
@@ -210,7 +212,7 @@ statically and will warn the developer of this improper usage.
 If all that you want to use a kobject for is to provide a reference counter
 for your structure, please use the struct kref instead; a kobject would be
 overkill.  For more information on how to use struct kref, please see the
-file Documentation/kref.txt in the Linux kernel source tree.
+file Documentation/kref.rst in the Linux kernel source tree.
 
 
 Creating "simple" kobjects
diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.rst
similarity index 99%
rename from Documentation/kprobes.txt
rename to Documentation/kprobes.rst
index 8baab8832c5b..ba15bd08a84a 100644
--- a/Documentation/kprobes.txt
+++ b/Documentation/kprobes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================
 Kernel Probes (Kprobes)
 =======================
diff --git a/Documentation/kref.txt b/Documentation/kref.rst
similarity index 99%
rename from Documentation/kref.txt
rename to Documentation/kref.rst
index 3af384156d7e..470e3c1bacdc 100644
--- a/Documentation/kref.txt
+++ b/Documentation/kref.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================
 Adding reference counters (krefs) to kernel objects
 ===================================================
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 6cced88de6da..3de3c95f01f6 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -610,7 +610,7 @@ Sysfs notes:
 	2010.
 
 	rfkill controller switch "tpacpi_bluetooth_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 
 Video output control -- /proc/acpi/ibm/video
@@ -1338,7 +1338,7 @@ Sysfs notes:
 	2010.
 
 	rfkill controller switch "tpacpi_wwan_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 
 EXPERIMENTAL: UWB
@@ -1357,7 +1357,7 @@ present and enabled in the BIOS.
 Sysfs notes:
 
 	rfkill controller switch "tpacpi_uwb_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 Adaptive keyboard
 -----------------
diff --git a/Documentation/ldm.txt b/Documentation/ldm.rst
similarity index 99%
rename from Documentation/ldm.txt
rename to Documentation/ldm.rst
index 12c571368e73..33fa13db5f67 100644
--- a/Documentation/ldm.txt
+++ b/Documentation/ldm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 LDM - Logical Disk Manager (Dynamic Disks)
 ==========================================
diff --git a/Documentation/locking/rt-mutex.rst b/Documentation/locking/rt-mutex.rst
index c365dc302081..6e3dcff802f9 100644
--- a/Documentation/locking/rt-mutex.rst
+++ b/Documentation/locking/rt-mutex.rst
@@ -4,7 +4,7 @@ RT-mutex subsystem with PI support
 
 RT-mutexes with priority inheritance are used to support PI-futexes,
 which enable pthread_mutex_t priority inheritance attributes
-(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.txt for more details
+(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.rst for more details
 about PI-futexes.]
 
 This technology was developed in the -rt tree and streamlined for
diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.rst
similarity index 99%
rename from Documentation/lockup-watchdogs.txt
rename to Documentation/lockup-watchdogs.rst
index 290840c160af..a60598bfd50f 100644
--- a/Documentation/lockup-watchdogs.txt
+++ b/Documentation/lockup-watchdogs.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================================================
 Softlockup detector and hardlockup detector (aka nmi_watchdog)
 ===============================================================
diff --git a/Documentation/lsm.txt b/Documentation/lsm.rst
similarity index 99%
rename from Documentation/lsm.txt
rename to Documentation/lsm.rst
index ad4dfd020e0d..4f0b1a6ea76c 100644
--- a/Documentation/lsm.txt
+++ b/Documentation/lsm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================================
 Linux Security Modules: General Security Hooks for Linux
 ========================================================
diff --git a/Documentation/lzo.txt b/Documentation/lzo.rst
similarity index 99%
rename from Documentation/lzo.txt
rename to Documentation/lzo.rst
index ca983328976b..36965db785af 100644
--- a/Documentation/lzo.txt
+++ b/Documentation/lzo.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================
 LZO stream format as understood by Linux's LZO decompressor
 ===========================================================
diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.rst
similarity index 99%
rename from Documentation/mailbox.txt
rename to Documentation/mailbox.rst
index 0ed95009cc30..02e754db3567 100644
--- a/Documentation/mailbox.txt
+++ b/Documentation/mailbox.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 The Common Mailbox Framework
 ============================
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 9d8146b6de73..ce301317680c 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -549,8 +549,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
 	[*] For information on bus mastering DMA and coherency please read:
 
 	    Documentation/PCI/pci.txt
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/DMA-API-HOWTO.rst
+	    Documentation/DMA-API.rst
 
 
 DATA DEPENDENCY BARRIERS (HISTORICAL)
@@ -1953,7 +1953,7 @@ There are some more advanced barrier functions:
      here.
 
      See the subsection "Kernel I/O barrier effects" for more information on
-     relaxed I/O accessors and the Documentation/DMA-API.txt file for more
+     relaxed I/O accessors and the Documentation/DMA-API.rst file for more
      information on consistent memory.
 
 
diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.rst
similarity index 99%
rename from Documentation/men-chameleon-bus.txt
rename to Documentation/men-chameleon-bus.rst
index 1b1f048aa748..2d6175229e58 100644
--- a/Documentation/men-chameleon-bus.txt
+++ b/Documentation/men-chameleon-bus.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 MEN Chameleon Bus
 =================
diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst
index f78d7bf27ff5..05f0feb99320 100644
--- a/Documentation/networking/scaling.rst
+++ b/Documentation/networking/scaling.rst
@@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
 an IRQ may be handled on any CPU. Because a non-negligible part of packet
 processing takes place in receive interrupt handling, it is advantageous
 to spread receive interrupts between CPUs. To manually adjust the IRQ
-affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
+affinity of each interrupt see Documentation/IRQ-affinity.rst. Some systems
 will be running irqbalance, a daemon that dynamically optimizes IRQ
 assignments and as a result may override any manual settings.
 
@@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::
 
 This file implements a bitmap of CPUs. RPS is disabled when it is zero
 (the default), in which case packets are processed on the interrupting
-CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
+CPU. Documentation/IRQ-affinity.rst explains how CPUs are assigned to
 the bitmap.
 
 
diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.rst
similarity index 99%
rename from Documentation/nommu-mmap.txt
rename to Documentation/nommu-mmap.rst
index 530fed08de2c..f7f75813dc9c 100644
--- a/Documentation/nommu-mmap.txt
+++ b/Documentation/nommu-mmap.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============================
 No-MMU memory mapping support
 =============================
diff --git a/Documentation/ntb.txt b/Documentation/ntb.rst
similarity index 99%
rename from Documentation/ntb.txt
rename to Documentation/ntb.rst
index 074a423c853c..1fa60198fd83 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 NTB Drivers
 ===========
diff --git a/Documentation/numastat.txt b/Documentation/numastat.rst
similarity index 99%
rename from Documentation/numastat.txt
rename to Documentation/numastat.rst
index aaf1667489f8..61f4c9ffb138 100644
--- a/Documentation/numastat.txt
+++ b/Documentation/numastat.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 Numa policy hit/miss statistics
 ===============================
diff --git a/Documentation/padata.txt b/Documentation/padata.rst
similarity index 99%
rename from Documentation/padata.txt
rename to Documentation/padata.rst
index b103d0c82000..f8369d18c846 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================================
 The padata parallel execution mechanism
 =======================================
diff --git a/Documentation/parport-lowlevel.txt b/Documentation/parport-lowlevel.rst
similarity index 99%
rename from Documentation/parport-lowlevel.txt
rename to Documentation/parport-lowlevel.rst
index 0633d70ffda7..b8574d83d328 100644
--- a/Documentation/parport-lowlevel.txt
+++ b/Documentation/parport-lowlevel.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 PARPORT interface documentation
 ===============================
diff --git a/Documentation/percpu-rw-semaphore.txt b/Documentation/percpu-rw-semaphore.rst
similarity index 99%
rename from Documentation/percpu-rw-semaphore.txt
rename to Documentation/percpu-rw-semaphore.rst
index 247de6410855..5c39c88d3719 100644
--- a/Documentation/percpu-rw-semaphore.txt
+++ b/Documentation/percpu-rw-semaphore.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================
 Percpu rw semaphores
 ====================
diff --git a/Documentation/phy.txt b/Documentation/phy.rst
similarity index 99%
rename from Documentation/phy.txt
rename to Documentation/phy.rst
index 457c3e0f86d6..129a45ccc857 100644
--- a/Documentation/phy.txt
+++ b/Documentation/phy.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 PHY subsystem
 =============
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.rst
similarity index 99%
rename from Documentation/pi-futex.txt
rename to Documentation/pi-futex.rst
index c33ba2befbf8..884ba7f2aa10 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================
 Lightweight PI-futexes
 ======================
diff --git a/Documentation/pnp.txt b/Documentation/pnp.rst
similarity index 99%
rename from Documentation/pnp.txt
rename to Documentation/pnp.rst
index bab2d10631f0..a66f19b2833c 100644
--- a/Documentation/pnp.txt
+++ b/Documentation/pnp.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 Linux Plug and Play Documentation
 =================================
diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.rst
similarity index 99%
rename from Documentation/preempt-locking.txt
rename to Documentation/preempt-locking.rst
index dce336134e54..e9ccd412df59 100644
--- a/Documentation/preempt-locking.txt
+++ b/Documentation/preempt-locking.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================================
 Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe
 ===========================================================================
diff --git a/Documentation/pwm.txt b/Documentation/pwm.rst
similarity index 99%
rename from Documentation/pwm.txt
rename to Documentation/pwm.rst
index 8fbf0aa3ba2d..78d06b7f5427 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================================
 Pulse Width Modulation (PWM) interface
 ======================================
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.rst
similarity index 99%
rename from Documentation/rbtree.txt
rename to Documentation/rbtree.rst
index 523d54b60087..5d39f696eaab 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 Red-black Trees (rbtree) in Linux
 =================================
diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.rst
similarity index 99%
rename from Documentation/remoteproc.txt
rename to Documentation/remoteproc.rst
index 77fb03acdbb4..71eb7728fcf3 100644
--- a/Documentation/remoteproc.txt
+++ b/Documentation/remoteproc.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================
 Remote Processor Framework
 ==========================
@@ -22,7 +24,7 @@ for remote processors that supports this kind of communication. This way,
 platform-specific remoteproc drivers only need to provide a few low-level
 handlers, and then all rpmsg drivers will then just work
 (for more information about the virtio-based rpmsg bus and its drivers,
-please read Documentation/rpmsg.txt).
+please read Documentation/rpmsg.rst).
 Registration of other types of virtio devices is now also possible. Firmwares
 just need to publish what kind of virtio devices do they support, and then
 remoteproc will add those devices. This makes it possible to reuse the
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.rst
similarity index 99%
rename from Documentation/rfkill.txt
rename to Documentation/rfkill.rst
index 7d3684e81df6..4da9994e9bb4 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 rfkill - RF kill switch support
 ===============================
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.rst
similarity index 99%
rename from Documentation/robust-futex-ABI.txt
rename to Documentation/robust-futex-ABI.rst
index 8a5d34abf726..6d359b46610c 100644
--- a/Documentation/robust-futex-ABI.txt
+++ b/Documentation/robust-futex-ABI.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================
 The robust futex ABI
 ====================
diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.rst
similarity index 99%
rename from Documentation/robust-futexes.txt
rename to Documentation/robust-futexes.rst
index 6c42c75103eb..f60ef0e78687 100644
--- a/Documentation/robust-futexes.txt
+++ b/Documentation/robust-futexes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================
 A description of what robust futexes are
 ========================================
diff --git a/Documentation/rpmsg.txt b/Documentation/rpmsg.rst
similarity index 99%
rename from Documentation/rpmsg.txt
rename to Documentation/rpmsg.rst
index 24b7a9e1a5f9..ad53931f3e43 100644
--- a/Documentation/rpmsg.txt
+++ b/Documentation/rpmsg.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================================
 Remote Processor Messaging (rpmsg) Framework
 ============================================
diff --git a/Documentation/rtc.txt b/Documentation/rtc.rst
similarity index 99%
rename from Documentation/rtc.txt
rename to Documentation/rtc.rst
index 688c95b11919..b79daa10c7a1 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================================
 Real Time Clock (RTC) Drivers for Linux
 =======================================
diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst
index 1f6d0b56d53e..87b5bb49b2f3 100644
--- a/Documentation/s390/vfio-ccw.rst
+++ b/Documentation/s390/vfio-ccw.rst
@@ -38,7 +38,7 @@ every detail. More information/reference could be found here:
   qemu/hw/s390x/css.c
 
 For vfio mediated device framework:
-- Documentation/vfio-mediated-device.txt
+- Documentation/vfio-mediated-device.rst
 
 Motivation of vfio-ccw
 ----------------------
@@ -322,5 +322,5 @@ Reference
 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)
 3. https://en.wikipedia.org/wiki/Channel_I/O
 4. Documentation/s390/cds.rst
-5. Documentation/vfio.txt
-6. Documentation/vfio-mediated-device.txt
+5. Documentation/vfio.rst
+6. Documentation/vfio-mediated-device.rst
diff --git a/Documentation/sgi-ioc4.txt b/Documentation/sgi-ioc4.rst
similarity index 99%
rename from Documentation/sgi-ioc4.txt
rename to Documentation/sgi-ioc4.rst
index 72709222d3c0..e6ed2e9b055b 100644
--- a/Documentation/sgi-ioc4.txt
+++ b/Documentation/sgi-ioc4.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================================
 SGI IOC4 PCI (multi function) device
 ====================================
diff --git a/Documentation/siphash.txt b/Documentation/siphash.rst
similarity index 99%
rename from Documentation/siphash.txt
rename to Documentation/siphash.rst
index 9965821ab333..833eef3a7956 100644
--- a/Documentation/siphash.txt
+++ b/Documentation/siphash.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================
 SipHash - a short input PRF
 ===========================
diff --git a/Documentation/smsc_ece1099.txt b/Documentation/smsc_ece1099.rst
similarity index 99%
rename from Documentation/smsc_ece1099.txt
rename to Documentation/smsc_ece1099.rst
index 079277421eaf..a403fcd7c64d 100644
--- a/Documentation/smsc_ece1099.txt
+++ b/Documentation/smsc_ece1099.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================================
 Msc Keyboard Scan Expansion/GPIO Expansion device
 =================================================
diff --git a/Documentation/speculation.txt b/Documentation/speculation.rst
similarity index 99%
rename from Documentation/speculation.txt
rename to Documentation/speculation.rst
index 50d7ea857cff..e240f01b0983 100644
--- a/Documentation/speculation.txt
+++ b/Documentation/speculation.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 This document explains potential effects of speculation, and how undesirable
 effects can be mitigated portably using common APIs.
 
diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.rst
similarity index 99%
rename from Documentation/static-keys.txt
rename to Documentation/static-keys.rst
index 9803e14639bf..bdf545e3a37f 100644
--- a/Documentation/static-keys.txt
+++ b/Documentation/static-keys.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 Static Keys
 ===========
diff --git a/Documentation/svga.txt b/Documentation/svga.rst
similarity index 99%
rename from Documentation/svga.txt
rename to Documentation/svga.rst
index b6c2f9acca92..1bfd54d9fb59 100644
--- a/Documentation/svga.txt
+++ b/Documentation/svga.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 =================================
diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.rst
similarity index 98%
rename from Documentation/switchtec.txt
rename to Documentation/switchtec.rst
index 30d6a64e53f7..6879c92de8e2 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================
 Linux Switchtec Support
 ========================
@@ -97,6 +99,6 @@ the following configuration settings:
 NT EP BAR 2 will be dynamically configured as a Direct Window, and
 the configuration file does not need to configure it explicitly.
 
-Please refer to Documentation/ntb.txt in Linux source tree for an overall
+Please refer to Documentation/ntb.rst in Linux source tree for an overall
 understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
 Hardware Driver in this stack.
diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.rst
similarity index 99%
rename from Documentation/sync_file.txt
rename to Documentation/sync_file.rst
index 496fb2c3b3e6..a65a67cc06fa 100644
--- a/Documentation/sync_file.txt
+++ b/Documentation/sync_file.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 Sync File API Guide
 ===================
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index f0c86fbb3b48..86fd3e35afa7 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -44,7 +44,7 @@ show up in /proc/sys/kernel:
 - kexec_load_disabled
 - kptr_restrict
 - l2cr                        [ PPC only ]
-- modprobe                    ==> Documentation/debugging-modules.txt
+- modprobe                    ==> Documentation/debugging-modules.rst
 - modules_disabled
 - msg_next_id		      [ sysv ipc ]
 - msgmax
@@ -327,7 +327,7 @@ when a hard lockup is detected.
    0 - don't panic on hard lockup
    1 - panic on hard lockup
 
-See Documentation/lockup-watchdogs.txt for more information.  This can
+See Documentation/lockup-watchdogs.rst for more information.  This can
 also be set using the nmi_watchdog kernel parameter.
 
 ==============================================================
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 690b3247ab23..6758767c85a8 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -566,7 +566,7 @@ trimming of allocations is initiated.
 
 The default value is 1.
 
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/nommu-mmap.rst for more information.
 
 ==============================================================
 
diff --git a/Documentation/tee.txt b/Documentation/tee.rst
similarity index 99%
rename from Documentation/tee.txt
rename to Documentation/tee.rst
index 56ea85ffebf2..b04ec6804fb1 100644
--- a/Documentation/tee.txt
+++ b/Documentation/tee.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 TEE subsystem
 =============
diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.rst
similarity index 99%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/this_cpu_ops.rst
index 5cb8b883ae83..a489d25ff549 100644
--- a/Documentation/this_cpu_ops.txt
+++ b/Documentation/this_cpu_ops.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 this_cpu operations
 ===================
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index 235ce2ab131a..af7ed1ca8273 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -40,7 +40,7 @@ Synopsis of kprobe_events
  MEMADDR	: Address where the probe is inserted.
  MAXACTIVE	: Maximum number of instances of the specified function that
 		  can be probed simultaneously, or 0 for the default value
-		  as defined in Documentation/kprobes.txt section 1.3.1.
+		  as defined in Documentation/kprobes.rst section 1.3.1.
 
  FETCHARGS	: Arguments. Each probe can have up to 128 args.
   %REG		: Fetch register REG
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
index db0b9d8619f1..f6ca27920b92 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -570,8 +570,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 
 	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
 
 	    Documentation/PCI/pci.txt
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/DMA-API-HOWTO.rst
+	    Documentation/DMA-API.rst
 
 
 데이터 의존성 배리어 (역사적)
@@ -1904,7 +1904,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효
 
      writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
      "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
-     위해선 Documentation/DMA-API.txt 문서를 참고하세요.
+     위해선 Documentation/DMA-API.rst 문서를 참고하세요.
 
 
 MMIO 쓰기 배리어
diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
index 956026d5cf82..0d9ec142e185 100644
--- a/Documentation/translations/zh_CN/IRQ.txt
+++ b/Documentation/translations/zh_CN/IRQ.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/IRQ.txt
+Chinese translated version of Documentation/IRQ.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Eric W. Biederman <ebiederman@xmission.com>
 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
 ---------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
+Documentation/IRQ.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
index 452271dda141..f5482e082399 100644
--- a/Documentation/translations/zh_CN/filesystems/sysfs.txt
+++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt
@@ -40,7 +40,7 @@ sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导
 数据结构及其属性，以及它们之间的关联到用户空间的方法。
 
 sysfs 始终与 kobject 的底层结构紧密相关。请阅读
-Documentation/kobject.txt 文档以获得更多关于 kobject 接口的
+Documentation/kobject.rst 文档以获得更多关于 kobject 接口的
 信息。
 
 
diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt
index 1f8127bdd415..4e9727990c10 100644
--- a/Documentation/translations/zh_CN/io_ordering.txt
+++ b/Documentation/translations/zh_CN/io_ordering.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/io_ordering.txt
+Chinese translated version of Documentation/io_ordering.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: Lin Yongting <linyongting@gmail.com>
 ---------------------------------------------------------------------
-Documentation/io_ordering.txt 的中文翻译
+Documentation/io_ordering.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.rst
similarity index 99%
rename from Documentation/unaligned-memory-access.txt
rename to Documentation/unaligned-memory-access.rst
index 1ee82419d8aa..848013a8bc10 100644
--- a/Documentation/unaligned-memory-access.txt
+++ b/Documentation/unaligned-memory-access.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 Unaligned Memory Accesses
 =========================
diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.rst
similarity index 99%
rename from Documentation/vfio-mediated-device.txt
rename to Documentation/vfio-mediated-device.rst
index c3f69bcaf96e..0ea57427e7e6 100644
--- a/Documentation/vfio-mediated-device.txt
+++ b/Documentation/vfio-mediated-device.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 =====================
@@ -408,7 +410,7 @@ card.
 References
 ==========
 
-1. See Documentation/vfio.txt for more information on VFIO.
+1. See Documentation/vfio.rst for more information on VFIO.
 2. struct mdev_driver in include/linux/mdev.h
 3. struct mdev_parent_ops in include/linux/mdev.h
 4. struct vfio_iommu_driver_ops in include/linux/vfio.h
diff --git a/Documentation/vfio.txt b/Documentation/vfio.rst
similarity index 99%
rename from Documentation/vfio.txt
rename to Documentation/vfio.rst
index f1a4d3c3ba0b..8a3fbd7d96f0 100644
--- a/Documentation/vfio.txt
+++ b/Documentation/vfio.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==================================
 VFIO - "Virtual Function I/O" [1]_
 ==================================
diff --git a/Documentation/video-output.txt b/Documentation/video-output.rst
similarity index 99%
rename from Documentation/video-output.txt
rename to Documentation/video-output.rst
index 56d6fa2e2368..5f7e3a9faea6 100644
--- a/Documentation/video-output.txt
+++ b/Documentation/video-output.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Video Output Switcher Control
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst
index 94a96371113e..f4ba329f011f 100644
--- a/Documentation/watchdog/hpwdt.rst
+++ b/Documentation/watchdog/hpwdt.rst
@@ -44,7 +44,7 @@ Last reviewed: 08/20/2018
  NOTE:
        More information about watchdog drivers in general, including the ioctl
        interface to /dev/watchdog can be found in
-       Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt.
+       Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.rst.
 
  Due to limitations in the iLO hardware, the NMI pretimeout if enabled,
  can only be set to 9 seconds.  Attempts to set pretimeout to other
diff --git a/Documentation/x86/topology.txt b/Documentation/x86/topology.txt
index 2953e3ec9a02..5d67136a7866 100644
--- a/Documentation/x86/topology.txt
+++ b/Documentation/x86/topology.txt
@@ -6,7 +6,7 @@ representation in the kernel. Update/change when doing changes to the
 respective code.
 
 The architecture-agnostic topology definitions are in
-Documentation/cputopology.txt. This file holds x86-specific
+Documentation/cputopology.rst. This file holds x86-specific
 differences/specialities which must not necessarily apply to the generic
 definitions. Thus, the way to read up on Linux topology on x86 is to start
 with the generic one and look at this one in parallel for the x86 specifics.
diff --git a/Documentation/xillybus.txt b/Documentation/xillybus.rst
similarity index 99%
rename from Documentation/xillybus.txt
rename to Documentation/xillybus.rst
index 2446ee303c09..d99f4a37e8b6 100644
--- a/Documentation/xillybus.txt
+++ b/Documentation/xillybus.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 Xillybus driver for generic FPGA interface
 ==========================================
diff --git a/Documentation/xz.txt b/Documentation/xz.rst
similarity index 99%
rename from Documentation/xz.txt
rename to Documentation/xz.rst
index b2220d03aa50..205edc6646d5 100644
--- a/Documentation/xz.txt
+++ b/Documentation/xz.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 XZ data compression in Linux
 ============================
diff --git a/Documentation/zorro.txt b/Documentation/zorro.rst
similarity index 99%
rename from Documentation/zorro.txt
rename to Documentation/zorro.rst
index 664072b017e3..1cf45d879c49 100644
--- a/Documentation/zorro.txt
+++ b/Documentation/zorro.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================
 Writing Device Drivers for Zorro Devices
 ========================================
diff --git a/MAINTAINERS b/MAINTAINERS
index 9c99c5f47381..66bcec263dbf 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4513,7 +4513,7 @@ DELL SYSTEMS MANAGEMENT BASE DRIVER (dcdbas)
 M:	Stuart Hayes <stuart.w.hayes@gmail.com>
 L:	platform-driver-x86@vger.kernel.org
 S:	Maintained
-F:	Documentation/dcdbas.txt
+F:	Documentation/dcdbas.rst
 F:	drivers/platform/x86/dcdbas.*
 
 DELL WMI NOTIFICATIONS DRIVER
@@ -4889,7 +4889,7 @@ M:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 R:	"Rafael J. Wysocki" <rafael@kernel.org>
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git
 S:	Supported
-F:	Documentation/kobject.txt
+F:	Documentation/kobject.rst
 F:	drivers/base/
 F:	fs/debugfs/
 F:	fs/sysfs/
@@ -5948,7 +5948,7 @@ M:	Ard Biesheuvel <ard.biesheuvel@linaro.org>
 L:	linux-efi@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/efi/efi.git
 S:	Maintained
-F:	Documentation/efi-stub.txt
+F:	Documentation/efi-stub.rst
 F:	arch/*/kernel/efi.c
 F:	arch/x86/boot/compressed/eboot.[ch]
 F:	arch/*/include/asm/efi.h
@@ -6494,7 +6494,7 @@ S:	Maintained
 F:	scripts/gcc-plugins/
 F:	scripts/gcc-plugin.sh
 F:	scripts/Makefile.gcc-plugins
-F:	Documentation/gcc-plugins.txt
+F:	Documentation/gcc-plugins.rst
 
 GASKET DRIVER FRAMEWORK
 M:	Rob Springer <rspringer@google.com>
@@ -6908,7 +6908,7 @@ M:	Herbert Xu <herbert@gondor.apana.org.au>
 L:	linux-crypto@vger.kernel.org
 S:	Odd fixes
 F:	Documentation/devicetree/bindings/rng/
-F:	Documentation/hw_random.txt
+F:	Documentation/hw_random.rst
 F:	drivers/char/hw_random/
 F:	include/linux/hw_random.h
 
@@ -6924,7 +6924,7 @@ L:	linux-remoteproc@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/hwspinlock.git
 F:	Documentation/devicetree/bindings/hwlock/
-F:	Documentation/hwspinlock.txt
+F:	Documentation/hwspinlock.rst
 F:	drivers/hwspinlock/
 F:	include/linux/hwspinlock.h
 
@@ -8107,7 +8107,7 @@ L:	tboot-devel@lists.sourceforge.net
 W:	http://tboot.sourceforge.net
 T:	hg http://tboot.hg.sourceforge.net:8000/hgroot/tboot/tboot
 S:	Supported
-F:	Documentation/intel_txt.txt
+F:	Documentation/intel_txt.rst
 F:	include/linux/tboot.h
 F:	arch/x86/kernel/tboot.c
 
@@ -8191,7 +8191,7 @@ L:	openipmi-developer@lists.sourceforge.net (moderated for non-subscribers)
 W:	http://openipmi.sourceforge.net/
 S:	Supported
 F:	Documentation/devicetree/bindings/ipmi/
-F:	Documentation/IPMI.txt
+F:	Documentation/IPMI.rst
 F:	drivers/char/ipmi/
 F:	include/linux/ipmi*
 F:	include/uapi/linux/ipmi*
@@ -8232,7 +8232,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
 M:	Marc Zyngier <marc.zyngier@arm.com>
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
-F:	Documentation/IRQ-domain.txt
+F:	Documentation/IRQ-domain.rst
 F:	include/linux/irqdomain.h
 F:	kernel/irq/irqdomain.c
 F:	kernel/irq/msi.c
@@ -8257,7 +8257,7 @@ F:	drivers/irqchip/
 ISA
 M:	William Breathitt Gray <vilhelm.gray@gmail.com>
 S:	Maintained
-F:	Documentation/isa.txt
+F:	Documentation/isa.rst
 F:	drivers/base/isa.c
 F:	include/linux/isa.h
 
@@ -8272,7 +8272,7 @@ F:	drivers/media/radio/radio-isa*
 ISAPNP
 M:	Jaroslav Kysela <perex@perex.cz>
 S:	Maintained
-F:	Documentation/isapnp.txt
+F:	Documentation/isapnp.rst
 F:	drivers/pnp/isapnp/
 F:	include/linux/isapnp.h
 
@@ -8711,7 +8711,7 @@ M:	Anil S Keshavamurthy <anil.s.keshavamurthy@intel.com>
 M:	"David S. Miller" <davem@davemloft.net>
 M:	Masami Hiramatsu <mhiramat@kernel.org>
 S:	Maintained
-F:	Documentation/kprobes.txt
+F:	Documentation/kprobes.rst
 F:	include/linux/kprobes.h
 F:	include/asm-generic/kprobes.h
 F:	kernel/kprobes.c
@@ -9069,7 +9069,7 @@ L:	linux-arch@vger.kernel.org
 S:	Supported
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
 F:	tools/memory-model/
-F:	Documentation/atomic_bitops.txt
+F:	Documentation/atomic_bitops.rst
 F:	Documentation/atomic_t.txt
 F:	Documentation/core-api/atomic_ops.rst
 F:	Documentation/core-api/refcount-vs-atomic.rst
@@ -9183,7 +9183,7 @@ M:	"Richard Russon (FlatCap)" <ldm@flatcap.org>
 L:	linux-ntfs-dev@lists.sourceforge.net
 W:	http://www.linux-ntfs.org/content/view/19/37/
 S:	Maintained
-F:	Documentation/ldm.txt
+F:	Documentation/ldm.rst
 F:	block/partitions/ldm.*
 
 LSILOGIC MPT FUSION DRIVERS (FC/SAS/SPI)
@@ -10109,7 +10109,7 @@ M:	Johannes Thumshirn <morbidrsa@gmail.com>
 S:	Maintained
 F:	drivers/mcb/
 F:	include/linux/mcb.h
-F:	Documentation/men-chameleon-bus.txt
+F:	Documentation/men-chameleon-bus.rst
 
 MEN F21BMC (Board Management Controller)
 M:	Andreas Werner <andreas.werner@men.de>
@@ -11761,7 +11761,7 @@ L:	linux-crypto@vger.kernel.org
 S:	Maintained
 F:	kernel/padata.c
 F:	include/linux/padata.h
-F:	Documentation/padata.txt
+F:	Documentation/padata.rst
 
 PANASONIC LAPTOP ACPI EXTRAS DRIVER
 M:	Harald Welte <laforge@gnumonks.org>
@@ -11785,7 +11785,7 @@ F:	drivers/parport/
 F:	include/linux/parport*.h
 F:	drivers/char/ppdev.c
 F:	include/uapi/linux/ppdev.h
-F:	Documentation/parport*.txt
+F:	Documentation/parport*.rst
 
 PARAVIRT_OPS INTERFACE
 M:	Juergen Gross <jgross@suse.com>
@@ -11960,7 +11960,7 @@ M:	Kurt Schwemmer <kurt.schwemmer@microsemi.com>
 M:	Logan Gunthorpe <logang@deltatee.com>
 L:	linux-pci@vger.kernel.org
 S:	Maintained
-F:	Documentation/switchtec.txt
+F:	Documentation/switchtec.rst
 F:	Documentation/ABI/testing/sysfs-class-switchtec
 F:	drivers/pci/switch/switchtec*
 F:	include/uapi/linux/switchtec_ioctl.h
@@ -12715,7 +12715,7 @@ M:	Thierry Reding <thierry.reding@gmail.com>
 L:	linux-pwm@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm.git
-F:	Documentation/pwm.txt
+F:	Documentation/pwm.rst
 F:	Documentation/devicetree/bindings/pwm/
 F:	include/linux/pwm.h
 F:	drivers/pwm/
@@ -13186,7 +13186,7 @@ Q:	http://patchwork.ozlabs.org/project/rtc-linux/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/abelloni/linux.git
 S:	Maintained
 F:	Documentation/devicetree/bindings/rtc/
-F:	Documentation/rtc.txt
+F:	Documentation/rtc.rst
 F:	drivers/rtc/
 F:	include/linux/rtc.h
 F:	include/uapi/linux/rtc.h
@@ -13236,7 +13236,7 @@ L:	linux-remoteproc@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/remoteproc.git
 S:	Maintained
 F:	Documentation/devicetree/bindings/remoteproc/
-F:	Documentation/remoteproc.txt
+F:	Documentation/remoteproc.rst
 F:	drivers/remoteproc/
 F:	include/linux/remoteproc.h
 
@@ -13247,7 +13247,7 @@ L:	linux-remoteproc@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/rpmsg.git
 S:	Maintained
 F:	drivers/rpmsg/
-F:	Documentation/rpmsg.txt
+F:	Documentation/rpmsg.rst
 F:	include/linux/rpmsg.h
 F:	include/linux/rpmsg/
 
@@ -13327,7 +13327,7 @@ W:	http://wireless.kernel.org/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211.git
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211-next.git
 S:	Maintained
-F:	Documentation/rfkill.txt
+F:	Documentation/rfkill.rst
 F:	Documentation/ABI/stable/sysfs-class-rfkill
 F:	net/rfkill/
 F:	include/linux/rfkill.h
@@ -14966,7 +14966,7 @@ SVGA HANDLING
 M:	Martin Mares <mj@ucw.cz>
 L:	linux-video@atrey.karlin.mff.cuni.cz
 S:	Maintained
-F:	Documentation/svga.txt
+F:	Documentation/svga.rst
 F:	arch/x86/boot/video*
 
 SWIOTLB SUBSYSTEM
@@ -15003,7 +15003,7 @@ F:	drivers/dma-buf/dma-fence*
 F:	drivers/dma-buf/sw_sync.c
 F:	include/linux/sync_file.h
 F:	include/uapi/linux/sync_file.h
-F:	Documentation/sync_file.txt
+F:	Documentation/sync_file.rst
 T:	git git://anongit.freedesktop.org/drm/drm-misc
 
 SYNOPSYS ARC ARCHITECTURE
@@ -15329,7 +15329,7 @@ S:	Maintained
 F:	include/linux/tee_drv.h
 F:	include/uapi/linux/tee.h
 F:	drivers/tee/
-F:	Documentation/tee.txt
+F:	Documentation/tee.rst
 
 TEGRA ARCHITECTURE SUPPORT
 M:	Thierry Reding <thierry.reding@gmail.com>
@@ -16484,7 +16484,7 @@ M:	Alex Williamson <alex.williamson@redhat.com>
 L:	kvm@vger.kernel.org
 T:	git git://github.com/awilliam/linux-vfio.git
 S:	Maintained
-F:	Documentation/vfio.txt
+F:	Documentation/vfio.rst
 F:	drivers/vfio/
 F:	include/linux/vfio.h
 F:	include/uapi/linux/vfio.h
@@ -16493,7 +16493,7 @@ VFIO MEDIATED DEVICE DRIVERS
 M:	Kirti Wankhede <kwankhede@nvidia.com>
 L:	kvm@vger.kernel.org
 S:	Maintained
-F:	Documentation/vfio-mediated-device.txt
+F:	Documentation/vfio-mediated-device.rst
 F:	drivers/vfio/mdev/
 F:	include/linux/mdev.h
 F:	samples/vfio-mdev/
diff --git a/arch/Kconfig b/arch/Kconfig
index ed382b01209b..ba0a53b543e3 100644
--- a/arch/Kconfig
+++ b/arch/Kconfig
@@ -141,7 +141,7 @@ config HAVE_64BIT_ALIGNED_ACCESS
 	  accesses are required to be 64 bit aligned in this way even
 	  though it is not a 64 bit architecture.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config HAVE_EFFICIENT_UNALIGNED_ACCESS
@@ -160,7 +160,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
 	  problems with received packets if doing so would not help
 	  much.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config ARCH_USE_BUILTIN_BSWAP
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index c6c424466f8a..7b905429626b 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -1260,8 +1260,8 @@ config SMP
 	  uniprocessor machines. On a uniprocessor machine, the kernel
 	  will run faster if you say N here.
 
-	  See also <file:Documentation/x86/i386/IO-APIC.txt>,
-	  <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO available at
+	  See also <file:Documentation/x86/i386/IO-APIC.rst>,
+	  <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO available at
 	  <http://tldp.org/HOWTO/SMP-HOWTO.html>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/ia64/hp/common/sba_iommu.c b/arch/ia64/hp/common/sba_iommu.c
index 5a361e51cb1e..0334db406d68 100644
--- a/arch/ia64/hp/common/sba_iommu.c
+++ b/arch/ia64/hp/common/sba_iommu.c
@@ -915,7 +915,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dir: dma direction
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static dma_addr_t sba_map_page(struct device *dev, struct page *page,
 			       unsigned long poff, size_t size,
@@ -1036,7 +1036,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
 			   enum dma_data_direction dir, unsigned long attrs)
@@ -1113,7 +1113,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void *
 sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
@@ -1170,7 +1170,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
 			      dma_addr_t dma_handle, unsigned long attrs)
@@ -1433,7 +1433,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			    int nents, enum dma_data_direction dir,
@@ -1532,7 +1532,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			       int nents, enum dma_data_direction dir,
diff --git a/arch/ia64/sn/pci/pci_dma.c b/arch/ia64/sn/pci/pci_dma.c
index b7d42e4edc1f..f475fccea152 100644
--- a/arch/ia64/sn/pci/pci_dma.c
+++ b/arch/ia64/sn/pci/pci_dma.c
@@ -5,7 +5,7 @@
  *
  * Copyright (C) 2000,2002-2005 Silicon Graphics, Inc. All rights reserved.
  *
- * Routines for PCI DMA mapping.  See Documentation/DMA-API.txt for
+ * Routines for PCI DMA mapping.  See Documentation/DMA-API.rst for
  * a description of how these routines should be used.
  */
 
@@ -72,7 +72,7 @@ EXPORT_SYMBOL(sn_dma_set_mask);
  * that @dma_handle will have the %PCIIO_DMA_CMD flag set.
  *
  * This interface is usually used for "command" streams (e.g. the command
- * queue for a SCSI controller).  See Documentation/DMA-API.txt for
+ * queue for a SCSI controller).  See Documentation/DMA-API.rst for
  * more information.
  */
 static void *sn_dma_alloc_coherent(struct device *dev, size_t size,
diff --git a/arch/parisc/Kconfig b/arch/parisc/Kconfig
index f996a6b2df40..e1189b9df371 100644
--- a/arch/parisc/Kconfig
+++ b/arch/parisc/Kconfig
@@ -273,7 +273,7 @@ config SMP
 	  machines, but will use only one CPU of a multiprocessor machine.
 	  On a uniprocessor machine, the kernel will run faster if you say N.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/parisc/kernel/pci-dma.c b/arch/parisc/kernel/pci-dma.c
index 239162355b58..2bb63062f6c3 100644
--- a/arch/parisc/kernel/pci-dma.c
+++ b/arch/parisc/kernel/pci-dma.c
@@ -3,7 +3,7 @@
 ** PARISC 1.1 Dynamic DMA mapping support.
 ** This implementation is for PA-RISC platforms that do not support
 ** I/O TLBs (aka DMA address translation hardware).
-** See Documentation/DMA-API-HOWTO.txt for interface definitions.
+** See Documentation/DMA-API-HOWTO.rst for interface definitions.
 **
 **      (c) Copyright 1999,2000 Hewlett-Packard Company
 **      (c) Copyright 2000 Grant Grundler
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index 9883516e682c..a72f4f9e91f3 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -677,7 +677,7 @@ config SMP
 	  People using multiprocessor machines who say Y here should also say
 	  Y to "Enhanced Real Time Clock Support", below.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/sparc/Kconfig b/arch/sparc/Kconfig
index 7c93f3121ee6..6391fdc4a98e 100644
--- a/arch/sparc/Kconfig
+++ b/arch/sparc/Kconfig
@@ -178,7 +178,7 @@ config SMP
 	  Y to "Enhanced Real Time Clock Support", below. The "Advanced Power
 	  Management" code will be disabled if you say Y here.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/unicore32/include/asm/io.h b/arch/unicore32/include/asm/io.h
index cb1d8fd2b16b..86877df4b1ee 100644
--- a/arch/unicore32/include/asm/io.h
+++ b/arch/unicore32/include/asm/io.h
@@ -31,7 +31,7 @@ extern void __uc32_iounmap(volatile void __iomem *addr);
  * ioremap and friends.
  *
  * ioremap takes a PCI memory address, as specified in
- * Documentation/io-mapping.txt.
+ * Documentation/io-mapping.rst.
  *
  */
 #define ioremap(cookie, size)		__uc32_ioremap(cookie, size)
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index bf8cb068acf8..24edda6eac18 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -392,7 +392,7 @@ config SMP
 	  Management" code will be disabled if you say Y here.
 
 	  See also <file:Documentation/x86/i386/IO-APIC.txt>,
-	  <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO available at
+	  <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO available at
 	  <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
@@ -1940,7 +1940,7 @@ config EFI_STUB
           This kernel feature allows a bzImage to be loaded directly
 	  by EFI firmware without the use of a bootloader.
 
-	  See Documentation/efi-stub.txt for more information.
+	  See Documentation/efi-stub.rst for more information.
 
 config EFI_MIXED
 	bool "EFI mixed-mode support"
diff --git a/arch/x86/include/asm/dma-mapping.h b/arch/x86/include/asm/dma-mapping.h
index 6b15a24930e0..dfa443fe17c2 100644
--- a/arch/x86/include/asm/dma-mapping.h
+++ b/arch/x86/include/asm/dma-mapping.h
@@ -3,8 +3,8 @@
 #define _ASM_X86_DMA_MAPPING_H
 
 /*
- * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and
- * Documentation/DMA-API.txt for documentation.
+ * IOMMU interface. See Documentation/DMA-API-HOWTO.rst and
+ * Documentation/DMA-API.rst for documentation.
  */
 
 #include <linux/scatterlist.h>
diff --git a/arch/x86/kernel/amd_gart_64.c b/arch/x86/kernel/amd_gart_64.c
index bf7f13ea3c64..46d555c0c234 100644
--- a/arch/x86/kernel/amd_gart_64.c
+++ b/arch/x86/kernel/amd_gart_64.c
@@ -5,7 +5,7 @@
  * This allows to use PCI devices that only support 32bit addresses on systems
  * with more than 4GB.
  *
- * See Documentation/DMA-API-HOWTO.txt for the interface specification.
+ * See Documentation/DMA-API-HOWTO.rst for the interface specification.
  *
  * Copyright 2002 Andi Kleen, SuSE Labs.
  * Subject to the GNU General Public License v2 only.
diff --git a/block/partitions/Kconfig b/block/partitions/Kconfig
index 37b9710cc80a..51b28e1e225d 100644
--- a/block/partitions/Kconfig
+++ b/block/partitions/Kconfig
@@ -194,7 +194,7 @@ config LDM_PARTITION
 	  Normal partitions are now called Basic Disks under Windows 2000, XP,
 	  and Vista.
 
-	  For a fuller description read <file:Documentation/ldm.txt>.
+	  For a fuller description read <file:Documentation/ldm.rst>.
 
 	  If unsure, say N.
 
diff --git a/drivers/base/core.c b/drivers/base/core.c
index 4aeaa0c92bda..47abfd0d06aa 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -1063,7 +1063,7 @@ static void device_release(struct kobject *kobj)
 	else if (dev->class && dev->class->dev_release)
 		dev->class->dev_release(dev);
 	else
-		WARN(1, KERN_ERR "Device '%s' does not have a release() function, it is broken and must be fixed. See Documentation/kobject.txt.\n",
+		WARN(1, KERN_ERR "Device '%s' does not have a release() function, it is broken and must be fixed. See Documentation/kobject.rst.\n",
 			dev_name(dev));
 	kfree(p);
 }
diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
index 466ebd84ad17..110824a27510 100644
--- a/drivers/char/Kconfig
+++ b/drivers/char/Kconfig
@@ -291,7 +291,7 @@ config RTC
 	  and set the RTC in an SMP compatible fashion.
 
 	  If you think you have a use for such a device (such as periodic data
-	  sampling), then say Y here, and read <file:Documentation/rtc.txt>
+	  sampling), then say Y here, and read <file:Documentation/rtc.rst>
 	  for details.
 
 	  To compile this driver as a module, choose M here: the
@@ -313,7 +313,7 @@ config JS_RTC
 	  /dev/rtc.
 
 	  If you think you have a use for such a device (such as periodic data
-	  sampling), then say Y here, and read <file:Documentation/rtc.txt>
+	  sampling), then say Y here, and read <file:Documentation/rtc.rst>
 	  for details.
 
 	  To compile this driver as a module, choose M here: the
diff --git a/drivers/char/hw_random/core.c b/drivers/char/hw_random/core.c
index 95be7228f327..41acde92bedc 100644
--- a/drivers/char/hw_random/core.c
+++ b/drivers/char/hw_random/core.c
@@ -4,7 +4,7 @@
  * Copyright 2006 Michael Buesch <m@bues.ch>
  * Copyright 2005 (c) MontaVista Software, Inc.
  *
- * Please read Documentation/hw_random.txt for details on use.
+ * Please read Documentation/hw_random.rst for details on use.
  *
  * This software may be used and distributed according to the terms
  * of the GNU General Public License, incorporated herein by reference.
diff --git a/drivers/char/ipmi/Kconfig b/drivers/char/ipmi/Kconfig
index 94719fc6ff9d..df47923e5119 100644
--- a/drivers/char/ipmi/Kconfig
+++ b/drivers/char/ipmi/Kconfig
@@ -13,7 +13,7 @@ menuconfig IPMI_HANDLER
          IPMI is a standard for managing sensors (temperature,
          voltage, etc.) in a system.
 
-         See <file:Documentation/IPMI.txt> for more details on the driver.
+         See <file:Documentation/IPMI.rst> for more details on the driver.
 
 	 If unsure, say N.
 
diff --git a/drivers/char/ipmi/ipmi_si_hotmod.c b/drivers/char/ipmi/ipmi_si_hotmod.c
index 03140f6cdf6f..bcf84522d5ef 100644
--- a/drivers/char/ipmi/ipmi_si_hotmod.c
+++ b/drivers/char/ipmi/ipmi_si_hotmod.c
@@ -18,7 +18,7 @@ static int hotmod_handler(const char *val, const struct kernel_param *kp);
 
 module_param_call(hotmod, hotmod_handler, NULL, NULL, 0200);
 MODULE_PARM_DESC(hotmod, "Add and remove interfaces.  See"
-		 " Documentation/IPMI.txt in the kernel sources for the"
+		 " Documentation/IPMI.rst in the kernel sources for the"
 		 " gory details.");
 
 /*
diff --git a/drivers/char/ipmi/ipmi_si_intf.c b/drivers/char/ipmi/ipmi_si_intf.c
index f124a2d2bb9f..5efb5c2ee78e 100644
--- a/drivers/char/ipmi/ipmi_si_intf.c
+++ b/drivers/char/ipmi/ipmi_si_intf.c
@@ -977,7 +977,7 @@ static inline int ipmi_thread_busy_wait(enum si_sm_result smi_result,
  * that are not BT and do not have interrupts.  It starts spinning
  * when an operation is complete or until max_busy tells it to stop
  * (if that is enabled).  See the paragraph on kimid_max_busy_us in
- * Documentation/IPMI.txt for details.
+ * Documentation/IPMI.rst for details.
  */
 static int ipmi_thread(void *data)
 {
diff --git a/drivers/dma-buf/Kconfig b/drivers/dma-buf/Kconfig
index 2e5a0faa2cb1..ae3c798ea787 100644
--- a/drivers/dma-buf/Kconfig
+++ b/drivers/dma-buf/Kconfig
@@ -15,7 +15,7 @@ config SYNC_FILE
 	  associated with a buffer. When a job is submitted to the GPU a fence
 	  is attached to the buffer and is transferred via userspace, using Sync
 	  Files fds, to the DRM driver for example. More details at
-	  Documentation/sync_file.txt.
+	  Documentation/sync_file.rst.
 
 config SW_SYNC
 	bool "Sync File Validation Framework"
diff --git a/drivers/gpio/Kconfig b/drivers/gpio/Kconfig
index 50020cacf1b4..bd2ff8333172 100644
--- a/drivers/gpio/Kconfig
+++ b/drivers/gpio/Kconfig
@@ -1284,7 +1284,7 @@ config GPIO_BT8XX
 	  The card needs to be physically altered for using it as a
 	  GPIO card. For more information on how to build a GPIO card
 	  from a BT8xx TV card, see the documentation file at
-	  Documentation/bt8xxgpio.txt
+	  Documentation/bt8xxgpio.rst
 
 	  If unsure, say N.
 
diff --git a/drivers/parisc/sba_iommu.c b/drivers/parisc/sba_iommu.c
index afaf8e6aefe6..00a2675db798 100644
--- a/drivers/parisc/sba_iommu.c
+++ b/drivers/parisc/sba_iommu.c
@@ -670,7 +670,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dev: instance of PCI owned by the driver that's asking
  * @mask:  number of address bits this PCI device can handle
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int sba_dma_supported( struct device *dev, u64 mask)
 {
@@ -682,7 +682,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
 		return(0);
 	}
 
-	/* Documentation/DMA-API-HOWTO.txt tells drivers to try 64-bit
+	/* Documentation/DMA-API-HOWTO.rst tells drivers to try 64-bit
 	 * first, then fall back to 32-bit if that fails.
 	 * We are just "encouraging" 32-bit DMA masks here since we can
 	 * never allow IOMMU bypass unless we add special support for ZX1.
@@ -710,7 +710,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
  * @size:  number of bytes to map in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static dma_addr_t
 sba_map_single(struct device *dev, void *addr, size_t size,
@@ -800,7 +800,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
  * @size:  number of bytes mapped in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void
 sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
@@ -879,7 +879,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
 		gfp_t gfp, unsigned long attrs)
@@ -910,7 +910,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void
 sba_free(struct device *hwdev, size_t size, void *vaddr,
@@ -945,7 +945,7 @@ int dump_run_sg = 0;
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int
 sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
@@ -1029,7 +1029,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void 
 sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
diff --git a/drivers/pci/switch/Kconfig b/drivers/pci/switch/Kconfig
index aee28a5bb98f..c1f5226cd0e5 100644
--- a/drivers/pci/switch/Kconfig
+++ b/drivers/pci/switch/Kconfig
@@ -9,7 +9,7 @@ config PCI_SW_SWITCHTEC
 	 Enables support for the management interface for the MicroSemi
 	 Switchtec series of PCIe switches. Supports userspace access
 	 to submit MRPC commands to the switch via /dev/switchtecX
-	 devices. See <file:Documentation/switchtec.txt> for more
+	 devices. See <file:Documentation/switchtec.rst> for more
 	 information.
 
 endmenu
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index a1ed13183559..91b63cd4d48d 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -117,7 +117,7 @@ config DCDBAS
 	  Interrupts (SMIs) and Host Control Actions (system power cycle or
 	  power off after OS shutdown) on certain Dell systems.
 
-	  See <file:Documentation/dcdbas.txt> for more details on the driver
+	  See <file:Documentation/dcdbas.rst> for more details on the driver
 	  and the Dell systems on which Dell systems management software makes
 	  use of this driver.
 
@@ -258,7 +258,7 @@ config DELL_RBU
 	 DELL system. Note you need a Dell OpenManage or Dell Update package (DUP)
 	 supporting application to communicate with the BIOS regarding the new
 	 image for the image update to take effect.
-	 See <file:Documentation/dell_rbu.txt> for more details on the driver.
+	 See <file:Documentation/dell_rbu.rst> for more details on the driver.
 
 
 config FUJITSU_LAPTOP
diff --git a/drivers/platform/x86/dcdbas.c b/drivers/platform/x86/dcdbas.c
index 88bd7efafe14..cc21295fa972 100644
--- a/drivers/platform/x86/dcdbas.c
+++ b/drivers/platform/x86/dcdbas.c
@@ -6,7 +6,7 @@
  *  and Host Control Actions (power cycle or power off after OS shutdown) on
  *  Dell systems.
  *
- *  See Documentation/dcdbas.txt for more information.
+ *  See Documentation/dcdbas.rst for more information.
  *
  *  Copyright (C) 1995-2006 Dell Inc.
  *
diff --git a/drivers/platform/x86/dell_rbu.c b/drivers/platform/x86/dell_rbu.c
index 031c68903583..9beb45bcffee 100644
--- a/drivers/platform/x86/dell_rbu.c
+++ b/drivers/platform/x86/dell_rbu.c
@@ -23,7 +23,7 @@
  * on every time the packet data is written. This driver requires an
  * application to break the BIOS image in to fixed sized packet chunks.
  *
- * See Documentation/dell_rbu.txt for more info.
+ * See Documentation/dell_rbu.rst for more info.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License v2.0 as published by
diff --git a/drivers/pnp/isapnp/Kconfig b/drivers/pnp/isapnp/Kconfig
index a1af146d2d90..740607146e42 100644
--- a/drivers/pnp/isapnp/Kconfig
+++ b/drivers/pnp/isapnp/Kconfig
@@ -6,6 +6,6 @@ config ISAPNP
 	depends on ISA || COMPILE_TEST
 	help
 	  Say Y here if you would like support for ISA Plug and Play devices.
-	  Some information is in <file:Documentation/isapnp.txt>.
+	  Some information is in <file:Documentation/isapnp.rst>.
 
 	  If unsure, say Y.
diff --git a/drivers/vfio/Kconfig b/drivers/vfio/Kconfig
index 9de5ed38da83..edf824e6433e 100644
--- a/drivers/vfio/Kconfig
+++ b/drivers/vfio/Kconfig
@@ -25,7 +25,7 @@ menuconfig VFIO
 	select ANON_INODES
 	help
 	  VFIO provides a framework for secure userspace device drivers.
-	  See Documentation/vfio.txt for more details.
+	  See Documentation/vfio.rst for more details.
 
 	  If you don't know what to do here, say N.
 
diff --git a/drivers/vfio/mdev/Kconfig b/drivers/vfio/mdev/Kconfig
index 14fdb106a827..fd310018a0c2 100644
--- a/drivers/vfio/mdev/Kconfig
+++ b/drivers/vfio/mdev/Kconfig
@@ -5,7 +5,7 @@ config VFIO_MDEV
 	default n
 	help
 	  Provides a framework to virtualize devices.
-	  See Documentation/vfio-mediated-device.txt for more details.
+	  See Documentation/vfio-mediated-device.rst for more details.
 
 	  If you don't know what do here, say N.
 
diff --git a/include/asm-generic/bitops/atomic.h b/include/asm-generic/bitops/atomic.h
index dd90c9792909..6ee11717bb65 100644
--- a/include/asm-generic/bitops/atomic.h
+++ b/include/asm-generic/bitops/atomic.h
@@ -8,7 +8,7 @@
 
 /*
  * Implementation of atomic bitops using atomic-fetch ops.
- * See Documentation/atomic_bitops.txt for details.
+ * See Documentation/atomic_bitops.rst for details.
  */
 
 static inline void set_bit(unsigned int nr, volatile unsigned long *p)
diff --git a/include/linux/dma-mapping.h b/include/linux/dma-mapping.h
index 6309a721394b..7ff3fcd73cec 100644
--- a/include/linux/dma-mapping.h
+++ b/include/linux/dma-mapping.h
@@ -14,7 +14,7 @@
 
 /**
  * List of possible attributes associated with a DMA mapping. The semantics
- * of each attribute should be defined in Documentation/DMA-attributes.txt.
+ * of each attribute should be defined in Documentation/DMA-attributes.rst.
  *
  * DMA_ATTR_WRITE_BARRIER: DMA to a memory region with this attribute
  * forces all pending DMA writes to complete.
diff --git a/include/linux/hw_random.h b/include/linux/hw_random.h
index c0b93e0ff0c0..e533eac9942b 100644
--- a/include/linux/hw_random.h
+++ b/include/linux/hw_random.h
@@ -1,7 +1,7 @@
 /*
 	Hardware Random Number Generator
 
-	Please read Documentation/hw_random.txt for details on use.
+	Please read Documentation/hw_random.rst for details on use.
 
 	----------------------------------------------------------
 	This software may be used and distributed according to the terms
diff --git a/include/linux/io-mapping.h b/include/linux/io-mapping.h
index 58df02bd93c9..b90c540696a4 100644
--- a/include/linux/io-mapping.h
+++ b/include/linux/io-mapping.h
@@ -28,7 +28,7 @@
  * The io_mapping mechanism provides an abstraction for mapping
  * individual pages from an io device to the CPU in an efficient fashion.
  *
- * See Documentation/io-mapping.txt
+ * See Documentation/io-mapping.rst
  */
 
 struct io_mapping {
diff --git a/include/linux/jump_label.h b/include/linux/jump_label.h
index 3e113a1fa0f1..c3947cab2d27 100644
--- a/include/linux/jump_label.h
+++ b/include/linux/jump_label.h
@@ -68,7 +68,7 @@
  * Lacking toolchain and or architecture support, static keys fall back to a
  * simple conditional branch.
  *
- * Additional babbling in: Documentation/static-keys.txt
+ * Additional babbling in: Documentation/static-keys.rst
  */
 
 #ifndef __ASSEMBLY__
diff --git a/include/linux/kobject.h b/include/linux/kobject.h
index 1ab0d624fb36..07c3f4329df0 100644
--- a/include/linux/kobject.h
+++ b/include/linux/kobject.h
@@ -7,7 +7,7 @@
  * Copyright (c) 2006-2008 Greg Kroah-Hartman <greg@kroah.com>
  * Copyright (c) 2006-2008 Novell Inc.
  *
- * Please read Documentation/kobject.txt before using the kobject
+ * Please read Documentation/kobject.rst before using the kobject
  * interface, ESPECIALLY the parts about reference counts and object
  * destructors.
  */
diff --git a/include/linux/kobject_ns.h b/include/linux/kobject_ns.h
index 069aa2ebef90..8c86c4641739 100644
--- a/include/linux/kobject_ns.h
+++ b/include/linux/kobject_ns.h
@@ -8,7 +8,7 @@
  *
  * Split from kobject.h by David Howells (dhowells@redhat.com)
  *
- * Please read Documentation/kobject.txt before using the kobject
+ * Please read Documentation/kobject.rst before using the kobject
  * interface, ESPECIALLY the parts about reference counts and object
  * destructors.
  */
diff --git a/include/linux/rbtree.h b/include/linux/rbtree.h
index fcbeed4053ef..ba33f7068c50 100644
--- a/include/linux/rbtree.h
+++ b/include/linux/rbtree.h
@@ -23,7 +23,7 @@
   I know it's not the cleaner way,  but in C (not in C++) to get
   performances and genericity...
 
-  See Documentation/rbtree.txt for documentation and samples.
+  See Documentation/rbtree.rst for documentation and samples.
 */
 
 #ifndef	_LINUX_RBTREE_H
diff --git a/include/linux/rbtree_augmented.h b/include/linux/rbtree_augmented.h
index 9510c677ac70..36dfacd9905c 100644
--- a/include/linux/rbtree_augmented.h
+++ b/include/linux/rbtree_augmented.h
@@ -33,7 +33,7 @@
  * rb_insert_augmented() and rb_erase_augmented() are intended to be public.
  * The rest are implementation details you are not expected to depend on.
  *
- * See Documentation/rbtree.txt for documentation and samples.
+ * See Documentation/rbtree.rst for documentation and samples.
  */
 
 struct rb_augment_callbacks {
diff --git a/include/media/videobuf-dma-sg.h b/include/media/videobuf-dma-sg.h
index 01bd142b979d..50a549e5b477 100644
--- a/include/media/videobuf-dma-sg.h
+++ b/include/media/videobuf-dma-sg.h
@@ -34,7 +34,7 @@
  *	does memory allocation too using vmalloc_32().
  *
  * videobuf_dma_*()
- *	see Documentation/DMA-API-HOWTO.txt, these functions to
+ *	see Documentation/DMA-API-HOWTO.rst, these functions to
  *	basically the same.  The map function does also build a
  *	scatterlist for the buffer (and unmap frees it ...)
  *
diff --git a/init/Kconfig b/init/Kconfig
index 70fa2d57ef49..448f8daa1204 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -1807,7 +1807,7 @@ config MMAP_ALLOW_UNINITIALIZED
 	  userspace.  Since that isn't generally a problem on no-MMU systems,
 	  it is normally safe to say Y here.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/nommu-mmap.rst for more information.
 
 config SYSTEM_DATA_VERIFICATION
 	def_bool n
diff --git a/kernel/dma/debug.c b/kernel/dma/debug.c
index a218e43cc382..37f33cfb7da2 100644
--- a/kernel/dma/debug.c
+++ b/kernel/dma/debug.c
@@ -1083,7 +1083,7 @@ static void check_unmap(struct dma_debug_entry *ref)
 	/*
 	 * Drivers should use dma_mapping_error() to check the returned
 	 * addresses of dma_map_single() and dma_map_page().
-	 * If not, print this warning message. See Documentation/DMA-API.txt.
+	 * If not, print this warning message. See Documentation/DMA-API.rst.
 	 */
 	if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
 		err_printk(ref->dev, entry,
diff --git a/kernel/padata.c b/kernel/padata.c
index 3e2633ae3bca..35123a3e9059 100644
--- a/kernel/padata.c
+++ b/kernel/padata.c
@@ -2,7 +2,7 @@
 /*
  * padata.c - generic interface to process data streams in parallel
  *
- * See Documentation/padata.txt for an api documentation.
+ * See Documentation/padata.rst for an api documentation.
  *
  * Copyright (C) 2008, 2009 secunet Security Networks AG
  * Copyright (C) 2008, 2009 Steffen Klassert <steffen.klassert@secunet.com>
diff --git a/lib/Kconfig b/lib/Kconfig
index fb453afff32e..7e050a759b3e 100644
--- a/lib/Kconfig
+++ b/lib/Kconfig
@@ -402,7 +402,7 @@ config INTERVAL_TREE
 
 	  See:
 
-		Documentation/rbtree.txt
+		Documentation/rbtree.rst
 
 	  for more information.
 
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index aa05f47f5762..1c9edf887951 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1662,7 +1662,7 @@ config PROVIDE_OHCI1394_DMA_INIT
 	  This code (~1k) is freed after boot. By then, the firewire stack
 	  in charge of the OHCI-1394 controllers should be used instead.
 
-	  See Documentation/debugging-via-ohci1394.txt for more information.
+	  See Documentation/debugging-via-ohci1394.rst for more information.
 
 menuconfig RUNTIME_TESTING_MENU
 	bool "Runtime Testing"
diff --git a/lib/crc32.c b/lib/crc32.c
index 4a20455d1f61..0de37ccc70dd 100644
--- a/lib/crc32.c
+++ b/lib/crc32.c
@@ -24,7 +24,7 @@
  * Version 2.  See the file COPYING for more details.
  */
 
-/* see: Documentation/crc32.txt for a description of algorithms */
+/* see: Documentation/crc32.rst for a description of algorithms */
 
 #include <linux/crc32.h>
 #include <linux/crc32poly.h>
diff --git a/lib/kobject.c b/lib/kobject.c
index aa89edcd2b63..c5870fae4ff3 100644
--- a/lib/kobject.c
+++ b/lib/kobject.c
@@ -6,7 +6,7 @@
  * Copyright (c) 2006-2007 Greg Kroah-Hartman <greg@kroah.com>
  * Copyright (c) 2006-2007 Novell Inc.
  *
- * Please see the file Documentation/kobject.txt for critical information
+ * Please see the file Documentation/kobject.rst for critical information
  * about using the kobject interface.
  */
 
@@ -639,7 +639,7 @@ static void kobject_cleanup(struct kobject *kobj)
 		 kobject_name(kobj), kobj, __func__, kobj->parent);
 
 	if (t && !t->release)
-		pr_debug("kobject: '%s' (%p): does not have a release() function, it is broken and must be fixed. See Documentation/kobject.txt.\n",
+		pr_debug("kobject: '%s' (%p): does not have a release() function, it is broken and must be fixed. See Documentation/kobject.rst.\n",
 			 kobject_name(kobj), kobj);
 
 	/* send "remove" if the caller did not do it but sent "add" */
diff --git a/lib/lzo/lzo1x_decompress_safe.c b/lib/lzo/lzo1x_decompress_safe.c
index 9e07e9ef1aad..a05ca85a64f9 100644
--- a/lib/lzo/lzo1x_decompress_safe.c
+++ b/lib/lzo/lzo1x_decompress_safe.c
@@ -31,7 +31,7 @@
  * depending on the base count. Since the base count is taken from a u8
  * and a few bits, it is safe to assume that it will always be lower than
  * or equal to 2*255, thus we can always prevent any overflow by accepting
- * two less 255 steps. See Documentation/lzo.txt for more information.
+ * two less 255 steps. See Documentation/lzo.rst for more information.
  */
 #define MAX_255_COUNT      ((((size_t)~0) / 255) - 2)
 
diff --git a/lib/xz/Kconfig b/lib/xz/Kconfig
index 12d2d777f36b..74f643b19f6a 100644
--- a/lib/xz/Kconfig
+++ b/lib/xz/Kconfig
@@ -4,7 +4,7 @@ config XZ_DEC
 	help
 	  LZMA2 compression algorithm and BCJ filters are supported using
 	  the .xz file format as the container. For integrity checking,
-	  CRC32 is supported. See Documentation/xz.txt for more information.
+	  CRC32 is supported. See Documentation/xz.rst for more information.
 
 if XZ_DEC
 
diff --git a/mm/Kconfig b/mm/Kconfig
index 96d199aa55fb..254246e66fba 100644
--- a/mm/Kconfig
+++ b/mm/Kconfig
@@ -370,7 +370,7 @@ config NOMMU_INITIAL_TRIM_EXCESS
 	  This option specifies the initial value of this option.  The default
 	  of 1 says that all excess pages should be trimmed.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/nommu-mmap.rst for more information.
 
 config TRANSPARENT_HUGEPAGE
 	bool "Transparent Hugepage Support"
diff --git a/mm/nommu.c b/mm/nommu.c
index b492fd1fcf9f..d7cf834b0746 100644
--- a/mm/nommu.c
+++ b/mm/nommu.c
@@ -4,7 +4,7 @@
  *  Replacement code for mm functions to support CPU's that don't
  *  have any form of memory management unit (thus no virtual memory).
  *
- *  See Documentation/nommu-mmap.txt
+ *  See Documentation/nommu-mmap.rst
  *
  *  Copyright (c) 2004-2008 David Howells <dhowells@redhat.com>
  *  Copyright (c) 2000-2003 David McCullough <davidm@snapgear.com>
diff --git a/samples/kprobes/kprobe_example.c b/samples/kprobes/kprobe_example.c
index 02be8984c32f..3be113db45fe 100644
--- a/samples/kprobes/kprobe_example.c
+++ b/samples/kprobes/kprobe_example.c
@@ -4,7 +4,7 @@
  * stack trace and selected registers when _do_fork() is called.
  *
  * For more information on theory of operation of kprobes, see
- * Documentation/kprobes.txt
+ * Documentation/kprobes.rst
  *
  * You will see the trace data in /var/log/messages and on the console
  * whenever _do_fork() is invoked to create a new process.
diff --git a/samples/kprobes/kretprobe_example.c b/samples/kprobes/kretprobe_example.c
index 7f9060f435cd..710889e7e5c0 100644
--- a/samples/kprobes/kretprobe_example.c
+++ b/samples/kprobes/kretprobe_example.c
@@ -10,7 +10,7 @@
  * If no func_name is specified, _do_fork is instrumented
  *
  * For more information on theory of operation of kretprobes, see
- * Documentation/kprobes.txt
+ * Documentation/kprobes.rst
  *
  * Build and insert the kernel module as done in the kprobe example.
  * You will see the trace data in /var/log/messages and on the console
diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
index 74271dba4f94..a58e83d3d64c 100644
--- a/scripts/gcc-plugins/Kconfig
+++ b/scripts/gcc-plugins/Kconfig
@@ -21,7 +21,7 @@ menuconfig GCC_PLUGINS
 	  GCC plugins are loadable modules that provide extra features to the
 	  compiler. They are useful for runtime instrumentation and static analysis.
 
-	  See Documentation/gcc-plugins.txt for details.
+	  See Documentation/gcc-plugins.rst for details.
 
 if GCC_PLUGINS
 
diff --git a/security/Kconfig b/security/Kconfig
index 353cfef71d4e..775f5bfe2cd3 100644
--- a/security/Kconfig
+++ b/security/Kconfig
@@ -120,7 +120,7 @@ config INTEL_TXT
 	  See <http://www.intel.com/technology/security/> for more information
 	  about Intel(R) TXT.
 	  See <http://tboot.sourceforge.net> for more information about tboot.
-	  See Documentation/intel_txt.txt for a description of how to enable
+	  See Documentation/intel_txt.rst for a description of how to enable
 	  Intel TXT support in a kernel boot.
 
 	  If you are unsure as to whether this is required, answer N.
diff --git a/tools/include/linux/rbtree.h b/tools/include/linux/rbtree.h
index 8e9ed4786269..617c4adb2caf 100644
--- a/tools/include/linux/rbtree.h
+++ b/tools/include/linux/rbtree.h
@@ -23,7 +23,7 @@
   I know it's not the cleaner way,  but in C (not in C++) to get
   performances and genericity...
 
-  See Documentation/rbtree.txt for documentation and samples.
+  See Documentation/rbtree.rst for documentation and samples.
 */
 
 #ifndef __TOOLS_LINUX_PERF_RBTREE_H
diff --git a/tools/include/linux/rbtree_augmented.h b/tools/include/linux/rbtree_augmented.h
index d008e1404580..ca544b017bc0 100644
--- a/tools/include/linux/rbtree_augmented.h
+++ b/tools/include/linux/rbtree_augmented.h
@@ -35,7 +35,7 @@
  * rb_insert_augmented() and rb_erase_augmented() are intended to be public.
  * The rest are implementation details you are not expected to depend on.
  *
- * See Documentation/rbtree.txt for documentation and samples.
+ * See Documentation/rbtree.rst for documentation and samples.
  */
 
 struct rb_augment_callbacks {
-- 
2.20.1

_______________________________________________
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Logan Gunthorpe]

On 2019-04-22 7:27 a.m., Mauro Carvalho Chehab wrote:

> 
> Later patches will move them to a better place and remove the
> :orphan: markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
>  Documentation/ABI/removed/sysfs-class-rfkill  |  2 +-
>  Documentation/ABI/stable/sysfs-class-rfkill   |  2 +-
>  Documentation/ABI/stable/sysfs-devices-node   |  2 +-
>  Documentation/ABI/testing/procfs-diskstats    |  2 +-
>  Documentation/ABI/testing/sysfs-block         |  2 +-
>  .../ABI/testing/sysfs-class-switchtec         |  2 +-
>  .../ABI/testing/sysfs-devices-system-cpu      |  4 +-
>  .../{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst}  |  2 +
>  Documentation/{DMA-API.txt => DMA-API.rst}    |  8 ++-
>  .../{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst}      |  4 +-
>  ...{DMA-attributes.txt => DMA-attributes.rst} |  2 +
>  Documentation/{IPMI.txt => IPMI.rst}          |  2 +
>  .../{IRQ-affinity.txt => IRQ-affinity.rst}    |  2 +
>  .../{IRQ-domain.txt => IRQ-domain.rst}        |  2 +
>  Documentation/{IRQ.txt => IRQ.rst}            |  2 +
>  .../{Intel-IOMMU.txt => Intel-IOMMU.rst}      |  2 +
>  Documentation/PCI/pci.txt                     |  8 +--
>  Documentation/{SAK.txt => SAK.rst}            |  2 +
>  Documentation/{SM501.txt => SM501.rst}        |  2 +
>  .../admin-guide/kernel-parameters.txt         |  6 +-
>  Documentation/admin-guide/l1tf.rst            |  2 +-
>  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
>  Documentation/block/biodoc.txt                |  2 +-
>  .../{bt8xxgpio.txt => bt8xxgpio.rst}          |  2 +
>  Documentation/{btmrvl.txt => btmrvl.rst}      |  2 +
>  ...-mapping.txt => bus-virt-phys-mapping.rst} |  4 +-
>  ...g-warn-once.txt => clearing-warn-once.rst} |  2 +
>  Documentation/{cpu-load.txt => cpu-load.rst}  |  2 +
>  .../{cputopology.txt => cputopology.rst}      |  2 +
>  Documentation/{crc32.txt => crc32.rst}        |  2 +
>  Documentation/{dcdbas.txt => dcdbas.rst}      |  2 +
>  ...ging-modules.txt => debugging-modules.rst} |  2 +
>  ...hci1394.txt => debugging-via-ohci1394.rst} |  2 +
>  Documentation/{dell_rbu.txt => dell_rbu.rst}  |  2 +
>  Documentation/device-mapper/statistics.rst    |  4 +-
>  .../devicetree/bindings/phy/phy-bindings.txt  |  2 +-
>  Documentation/{digsig.txt => digsig.rst}      |  2 +
>  Documentation/driver-api/usb/dma.rst          |  6 +-
>  Documentation/driver-model/device.rst         |  2 +-
>  Documentation/{efi-stub.txt => efi-stub.rst}  |  2 +
>  Documentation/{eisa.txt => eisa.rst}          |  2 +
>  Documentation/fb/vesafb.rst                   |  2 +-
>  Documentation/filesystems/sysfs.txt           |  2 +-
>  ...ex-requeue-pi.txt => futex-requeue-pi.rst} |  2 +
>  .../{gcc-plugins.txt => gcc-plugins.rst}      |  2 +
>  Documentation/gpu/drm-mm.rst                  |  2 +-
>  Documentation/{highuid.txt => highuid.rst}    |  2 +
>  .../{hw_random.txt => hw_random.rst}          |  2 +
>  .../{hwspinlock.txt => hwspinlock.rst}        |  2 +
>  Documentation/ia64/IRQ-redir.txt              |  2 +-
>  .../{intel_txt.txt => intel_txt.rst}          |  2 +
>  .../{io-mapping.txt => io-mapping.rst}        |  2 +
>  .../{io_ordering.txt => io_ordering.rst}      |  2 +
>  Documentation/{iostats.txt => iostats.rst}    |  2 +
>  ...flags-tracing.txt => irqflags-tracing.rst} |  2 +
>  Documentation/{isa.txt => isa.rst}            |  2 +
>  Documentation/{isapnp.txt => isapnp.rst}      |  2 +
>  ...hreads.txt => kernel-per-CPU-kthreads.rst} |  4 +-
>  Documentation/{kobject.txt => kobject.rst}    |  4 +-
>  Documentation/{kprobes.txt => kprobes.rst}    |  2 +
>  Documentation/{kref.txt => kref.rst}          |  2 +
>  Documentation/laptops/thinkpad-acpi.txt       |  6 +-
>  Documentation/{ldm.txt => ldm.rst}            |  2 +
>  Documentation/locking/rt-mutex.rst            |  2 +-
>  ...kup-watchdogs.txt => lockup-watchdogs.rst} |  2 +
>  Documentation/{lsm.txt => lsm.rst}            |  2 +
>  Documentation/{lzo.txt => lzo.rst}            |  2 +
>  Documentation/{mailbox.txt => mailbox.rst}    |  2 +
>  Documentation/memory-barriers.txt             |  6 +-
>  ...hameleon-bus.txt => men-chameleon-bus.rst} |  2 +
>  Documentation/networking/scaling.rst          |  4 +-
>  .../{nommu-mmap.txt => nommu-mmap.rst}        |  2 +
>  Documentation/{ntb.txt => ntb.rst}            |  2 +
>  Documentation/{numastat.txt => numastat.rst}  |  2 +
>  Documentation/{padata.txt => padata.rst}      |  2 +
>  ...port-lowlevel.txt => parport-lowlevel.rst} |  2 +
>  ...-semaphore.txt => percpu-rw-semaphore.rst} |  2 +
>  Documentation/{phy.txt => phy.rst}            |  2 +
>  Documentation/{pi-futex.txt => pi-futex.rst}  |  2 +
>  Documentation/{pnp.txt => pnp.rst}            |  2 +
>  ...reempt-locking.txt => preempt-locking.rst} |  2 +
>  Documentation/{pwm.txt => pwm.rst}            |  2 +
>  Documentation/{rbtree.txt => rbtree.rst}      |  2 +
>  .../{remoteproc.txt => remoteproc.rst}        |  4 +-
>  Documentation/{rfkill.txt => rfkill.rst}      |  2 +
>  ...ust-futex-ABI.txt => robust-futex-ABI.rst} |  2 +
>  ...{robust-futexes.txt => robust-futexes.rst} |  2 +
>  Documentation/{rpmsg.txt => rpmsg.rst}        |  2 +
>  Documentation/{rtc.txt => rtc.rst}            |  2 +
>  Documentation/s390/vfio-ccw.rst               |  6 +-
>  Documentation/{sgi-ioc4.txt => sgi-ioc4.rst}  |  2 +
>  Documentation/{siphash.txt => siphash.rst}    |  2 +
>  .../{smsc_ece1099.txt => smsc_ece1099.rst}    |  2 +
>  .../{speculation.txt => speculation.rst}      |  2 +
>  .../{static-keys.txt => static-keys.rst}      |  2 +
>  Documentation/{svga.txt => svga.rst}          |  2 +
>  .../{switchtec.txt => switchtec.rst}          |  4 +-

For all the switchtec changes:

Acked-by: Logan Gunthorpe <logang-OTvnGxWRz7hWk0Htik3J/w@public.gmane.org>

Thanks,

Logan

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:

>  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +

What's happend to atomic_t.txt, also NAK, I still occationally touch
these files.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mike Snitzer]

On Tue, Apr 23 2019 at  4:31am -0400,
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> 
> >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> 
> What's happend to atomic_t.txt, also NAK, I still occationally touch
> these files.

Seems Mauro's point is in the future we need to touch these .rst files
in terms of ReST compatible changes.

I'm dreading DM documentation changes in the future.. despite Mauro and
Jon Corbet informing me that ReST is simple, etc.

Mike

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:
> On Tue, Apr 23 2019 at  4:31am -0400,
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > 
> > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> > 
> > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > these files.
> 
> Seems Mauro's point is in the future we need to touch these .rst files
> in terms of ReST compatible changes.
> 
> I'm dreading DM documentation changes in the future.. despite Mauro and
> Jon Corbet informing me that ReST is simple, etc.

Well, it _can_ be simple, I've seen examples of rst that were not far
from generated HTML contents. And I must give Jon credit for not
accepting that atrocious crap.

But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
give me anything in return. There is no upside, only worse text files :/

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mike Snitzer]

On Tue, Apr 23 2019 at  9:01am -0400,
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:
> > On Tue, Apr 23 2019 at  4:31am -0400,
> > Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> > 
> > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > > 
> > > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> > > 
> > > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > > these files.
> > 
> > Seems Mauro's point is in the future we need to touch these .rst files
> > in terms of ReST compatible changes.
> > 
> > I'm dreading DM documentation changes in the future.. despite Mauro and
> > Jon Corbet informing me that ReST is simple, etc.
> 
> Well, it _can_ be simple, I've seen examples of rst that were not far
> from generated HTML contents. And I must give Jon credit for not
> accepting that atrocious crap.
> 
> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> give me anything in return. There is no upside, only worse text files :/

Right, but these changes aren't meant for our benefit.  They are for
users who get cleaner web accessible Linux kernel docs.  Seems the
decision has been made that the users' benefit, and broader
modernization of Linux docs, outweighs the inconvenience for engineers
who maintain the content of said documentation.

This kind of thing happens a lot these days: pile on engineers, they can
take it :/

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 09:21:00 -0400
Mike Snitzer <snitzer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> escreveu:

> On Tue, Apr 23 2019 at  9:01am -0400,
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:  
> > > On Tue, Apr 23 2019 at  4:31am -0400,
> > > Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> > >   
> > > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > > >   
> > > > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +  
> > > > 
> > > > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > > > these files.  
> > > 
> > > Seems Mauro's point is in the future we need to touch these .rst files
> > > in terms of ReST compatible changes.
> > > 
> > > I'm dreading DM documentation changes in the future.. despite Mauro and
> > > Jon Corbet informing me that ReST is simple, etc.  

ReST is simple[1], and neither Jon or me wants to burden developers to
use complex documents all over the Kernel tree. ReST is just a way to 
make the documents with similar visual. The main advantage of ReST is
that documents can be better organized, as they will be inside some
index.rst file.

[1] Ok, as any document, you could write an easy or hard to read stuff.
The way we're using on most places is to be just a coding style with
benefits. I wrote a quick 101 guide to ReST at the end, with all you
probably need to know about it.

So, for example, in the specific case of atomic_bitops, all it takes for
it to be parsed by Sphinx is to rename it to .rst. With that, it can be
added into an index.rst file, like at Documentation/driver-api/index.rst.

The document, as is, will be displayed like this:

	https://www.infradead.org/~mchehab/rst_conversion/driver-api/atomic_bitops.html?highlight=atomic_t

And the original text file can also be seen from the output data:

	https://www.infradead.org/~mchehab/rst_conversion/_sources/driver-api/atomic_bitops.rst.txt

> > 
> > Well, it _can_ be simple, I've seen examples of rst that were not far
> > from generated HTML contents. And I must give Jon credit for not
> > accepting that atrocious crap.
> > 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/  
> 
> Right, but these changes aren't meant for our benefit.  They are for
> users who get cleaner web accessible Linux kernel docs.  Seems the
> decision has been made that the users' benefit, and broader
> modernization of Linux docs, outweighs the inconvenience for engineers
> who maintain the content of said documentation.

> This kind of thing happens a lot these days: pile on engineers, they can
> take it :/

Yes, that's the main goal: ensure that more people will see the
documents and write less crappy code. So, overall, reducing the
time we spent with reviews of bad code.


----

=================================
My 101 ReST quick reference guide
=================================

Basically, a "quick" ReST guide for those that don't want to learn it
and like to have an easy to read text document would be

1) to format documents like:

	=========
	Doc Title
	=========

	foo chapter
	===========

	bar section
	-----------

	foobar sub-section
	^^^^^^^^^^^^^^^^^^

	foobarzeta sub-sub-section
	..........................

(the actual character used to mark the titles can be different,
provided that you use the same character for the same title
level - the above is just the way *I* use, as it makes easier for
me to remember the title level).

2) remember that ReST considers new lines with same indentation as
   belonging to the same paragraph. So,

	foo
	bar

is identical to:

	foo bar

while
	foo
	   bar

will make "foo" bold, and write bar on the next line. So, if you
want to have them on two separate lines on its output, it should
be either write it as:

	foo

	bar

or you could use a list:

	- foo
	- bar

Btw, *a lot* of Kernel documents already have the above format.

3) literal values should be either inside ``foo``, `foo` or on an
   indented line after a ::, like:

	example::

		# some_command_to_be_typed

If you follow those three simple rules, your document will be properly
parsed. The above covers 90% of what we normally use.

Tables are also easy to write there, as it recognizes two ways to write
ascii tables, with are already popular ways to write them.

So, those are valid tables:

Without a title:

	===   ===============
	foo   foo description
	bar   bar description
	===   ===============


	+-------+-----------------+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

With a title:

	===== ===============
	field description
	===== ===============
	foo   foo description
	bar   bar description
	===   ===============

	+-------+-----------------+
	| field | description     |
	+=======+=================+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

This is not too different on what we usually do on documents - except that
some documents sometimes use UTF8, or a different character set to mark the
table lines. So the "conversion" is simply to follow one of the above
styles.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 15:01:32 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> give me anything in return. There is no upside, only worse text files :/

So I believe it gives even you one thing in return: documentation that is
more accessible for both readers and authors.  More readable docs should
lead to more educated developers who understand the code better.  More
writable docs will bring more people in to help to improve them.  The
former effect has been reported in the GPU community, where they say that
the quality of submissions has improved along with the docs.  The latter
can be observed in the increased number of people working on the docs
overall, something that Linus noted in the 5.1-rc1 announcement.

Hopefully that's worth something :)

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 10:30:53AM -0600, Jonathan Corbet wrote:
> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
> 
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.

I know I'm an odd duck; but no. They're _less_ accessible for me, as
both a reader and author. They look 'funny' when read as a text file
(the only way it makes sense to read them; I spend 99% of my time on a
computer looking at monospace text interfaces; mutt, vim and console, in
that approximate order).

When writing, I now have to be bothered about this format crap over just
trying to write a coherent document.

Look at crap like this:

"The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and"

That should've been written like:

"The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
and"

Heck, that paragraph isn't even properly flowed.

Then there's the endless stuck ':' key, and the mysterious "''" because
\" isn't a character, oh wait.

Bah..

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote:
> I know I'm an odd duck; but no. They're _less_ accessible for me, as
> both a reader and author. They look 'funny' when read as a text file
> (the only way it makes sense to read them; I spend 99% of my time on a
> computer looking at monospace text interfaces; mutt, vim and console, in
> that approximate order).

+1

It is probably fine to stare at them here
https://www.kernel.org/doc/html/latest/ and the end result is good
for showing them in browsers but after this conversion, it is
getting more and more painful to work with those files. For example,
Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go
sort out rest muck first just so that I can read it.

I think we can simply leave some text files be text files and be done
with it.

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 19:20:06 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote:
> > I know I'm an odd duck; but no. They're _less_ accessible for me, as
> > both a reader and author. They look 'funny' when read as a text file
> > (the only way it makes sense to read them; I spend 99% of my time on a
> > computer looking at monospace text interfaces; mutt, vim and console, in
> > that approximate order).  
> 
> +1
> 
> It is probably fine to stare at them here
> https://www.kernel.org/doc/html/latest/ and the end result is good
> for showing them in browsers but after this conversion, it is
> getting more and more painful to work with those files. For example,
> Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go
> sort out rest muck first just so that I can read it.

That's my view about how that specific file would be after
converted to ReST:

	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames

I don't have any troubles reading/understanding it as a plain text
file, and its html output is also nice (although Sphinx 1.7.8 seems to
have some issues when parsing some cells - probably due to some bug):

	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html

> 
> I think we can simply leave some text files be text files and be done
> with it.

Changbin's approach was somewhat close to what you want. He simply
prepended the tables with ::, in order to show them as plain old
ascii:

	https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org/

Both equally works, from ReST conversion PoV. I'm fine ether way.

I prefer my approach, as, IMHO, it is visually nicer on both text and
html versions, but his approach is likely easier to maintain, as doing
ascii artwork by hand is sometimes painful.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 05:05:02PM -0300, Mauro Carvalho Chehab wrote:
> That's my view about how that specific file would be after
> converted to ReST:
> 
> 	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames
> 
> I don't have any troubles reading/understanding it as a plain text
> file,

If that is all the changes it would need, then I guess that's ok. Btw,
those rst-conversion patches don't really show what got changed. Dunno
if git can even show that properly. I diffed the two files by hand to
see what got changed, see end of mail.

So I guess if table in rst means, one needs to draw rows and columns, I
guess that's ok. It's not like I have to do it every day.

But exactly this - *having* to do rst formatting would mean a lot of
getting used to and people writing something which is not necessarily
correct rst and someone else fixing up after them.

Another pain point is changing the file paths. Without cscope I would've
been cursing each time I'm looking for kernel-parameters.txt, for
example. First of all, it is in Documentation/admin-guide/ now and then
there's Documentation/admin-guide/kernel-parameters.rst too.

I guess the .rst sucks in the .txt file and shows it monospaced. Oh
well.

So* I'd suggest having as less markup in those files as possible and if
it is needed, automate adding the needed markup, as Jon suggested.

The perfect example was the one which Peter gave and I had to paste in a
thread today:

"The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and"

That is very unreadable.

Anyway, stuff like that. Just giving my feedback here in case you're
interested. :-)

> and its html output is also nice (although Sphinx 1.7.8 seems to
> have some issues when parsing some cells - probably due to some bug):
> 
> 	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html

I don't know how that looks in your browser but in mine those addresses
are not in monospaced font and there's no properly reading them.

And yap, the cells parsing fun I see too.

> Changbin's approach was somewhat close to what you want. He simply
> prepended the tables with ::, in order to show them as plain old
> ascii:
> 
> 	https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org/

Yap, that's better.

I mean, the file is just as readable in plain old ASCII, if not even
more so. At least to me but I prefer simple things so...

> 
> Both equally works, from ReST conversion PoV. I'm fine ether way.
> 
> I prefer my approach, as, IMHO, it is visually nicer on both text and
> html versions, but his approach is likely easier to maintain, as doing
> ascii artwork by hand is sometimes painful.

Yap.

Thx.

---
--- mm.old	2019-04-23 23:18:55.954335784 +0200
+++ mm.new	2019-04-23 23:18:48.122335821 +0200
@@ -18,51 +18,68 @@ Notes:
    notation than "16 EB", which few will recognize at first sight as 16 exabytes.
    It also shows it nicely how incredibly large 64-bit address space is.
 
-========================================================================================================================
-    Start addr    |   Offset   |     End addr     |  Size   | VM area description
-========================================================================================================================
-                  |            |                  |         |
- 0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
-                  |            |                  |         |
- 0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
-                  |            |                  |         |     virtual memory addresses up to the -128 TB
-                  |            |                  |         |     starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
-                                                            |
-                                                            | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
-                  |            |                  |         |
- ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor
- ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI
- ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)
- ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole
- ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)
- ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole
- ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)
- ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole
- ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
-                                                            |
-                                                            | Identical layout to the 56-bit one from here on:
-____________________________________________________________|____________________________________________________________
-                  |            |                  |         |
- fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
-                  |            |                  |         | vaddr_end for KASLR
- fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
- fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
- ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
- ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
- ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
- ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048    MB |                  |         |
- ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 |  -16    MB |                  |         |
-    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
- ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
++=================+============+==================+=========+===========================================================+
+|                 |            |                  |         |                                                           |
+|0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm               |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                 |            |                  |         |                                                           |
+|0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical       |
+|                 |            |                  |         | virtual memory addresses up to the -128 TB                |
+|                 |            |                  |         | starting offset of kernel mappings.                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                      **Kernel-space virtual memory, shared between all processes:**                                   |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor              |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                         **Identical layout to the 56-bit one from here on:**                                          |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
+|                 |            |                  |         | vaddr_end for KASLR                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |-2048    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff000000 |  -16    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
 
 
 ====================================================
@@ -76,51 +93,66 @@ Notes:
    offset and many of the regions expand to support the much larger physical
    memory supported.
 
-========================================================================================================================
-    Start addr    |   Offset   |     End addr     |  Size   | VM area description
-========================================================================================================================
-                  |            |                  |         |
- 0000000000000000 |    0       | 00ffffffffffffff |   64 PB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
-                  |            |                  |         |
- 0100000000000000 |  +64    PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical
-                  |            |                  |         |     virtual memory addresses up to the -64 PB
-                  |            |                  |         |     starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
-                                                            |
-                                                            | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
-                  |            |                  |         |
- ff00000000000000 |  -64    PB | ff0fffffffffffff |    4 PB | ... guard hole, also reserved for hypervisor
- ff10000000000000 |  -60    PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI
- ff11000000000000 |  -59.75 PB | ff90ffffffffffff |   32 PB | direct mapping of all physical memory (page_offset_base)
- ff91000000000000 |  -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole
- ffa0000000000000 |  -24    PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)
- ffd2000000000000 |  -11.5  PB | ffd3ffffffffffff |  0.5 PB | ... unused hole
- ffd4000000000000 |  -11    PB | ffd5ffffffffffff |  0.5 PB | virtual memory map (vmemmap_base)
- ffd6000000000000 |  -10.5  PB | ffdeffffffffffff | 2.25 PB | ... unused hole
- ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
-                                                            |
-                                                            | Identical layout to the 47-bit one from here on:
-____________________________________________________________|____________________________________________________________
-                  |            |                  |         |
- fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
-                  |            |                  |         | vaddr_end for KASLR
- fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
- fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
- ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
- ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
- ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
- ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048    MB |                  |         |
- ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 |  -16    MB |                  |         |
-    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
- ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
++=================+============+==================+=========+===========================================================+
+|0000000000000000 |    0       | 00ffffffffffffff |   64 PB | user-space virtual memory, different per mm               |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|0100000000000000 |  +64    PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical |
+|                 |            |                  |         | virtual memory addresses up to the -64 PB                 |
+|                 |            |                  |         | starting offset of kernel mappings.                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                       **Kernel-space virtual memory, shared between all processes:**                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff00000000000000 |  -64    PB | ff0fffffffffffff |    4 PB | ... guard hole, also reserved for hypervisor              |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff10000000000000 |  -60    PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff11000000000000 |  -59.75 PB | ff90ffffffffffff |   32 PB | direct mapping of all physical memory (page_offset_base)  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff91000000000000 |  -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffa0000000000000 |  -24    PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd2000000000000 |  -11.5  PB | ffd3ffffffffffff |  0.5 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd4000000000000 |  -11    PB | ffd5ffffffffffff |  0.5 PB | virtual memory map (vmemmap_base)                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd6000000000000 |  -10.5  PB | ffdeffffffffffff | 2.25 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                           **Identical layout to the 47-bit one from here on:**                                        |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
+|                 |            |                  |         | vaddr_end for KASLR                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |-2048    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff000000 |  -16    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
 
 Architecture defines a 64-bit virtual address. Implementations can support
 less. Currently supported are 48- and 57-bit virtual addresses. Bits 63

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> wrote:

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Remember that most of our docs are 99% RST even though they were written
by people who had never even heard of RST.  I really don't think it's a
big deal - a far smaller cognitive load than trying to keep up with any
given subsystem's variable-declaration-ordering rules, for example :)

> Another pain point is changing the file paths. Without cscope I would've
> been cursing each time I'm looking for kernel-parameters.txt, for
> example. First of all, it is in Documentation/admin-guide/ now and then
> there's Documentation/admin-guide/kernel-parameters.rst too.

Moving of files has nothing to do with RST, of course.  That you can
blame entirely on me trying to bring some order to Documentation/.  As a
predecessor of mine once put it (https://lkml.org/lkml/2007/7/3/422):

	Documentation/* is a gigantic mess, currently organized based on
	where random passers-by put things down last.

When other parts of the kernel tree turn out to be organized in
less-than-useful ways, we move things around.  I'm trying to do the same
in Documentation/, with an attempt to be sympathetic toward our readers,
sort things by intended audience, and create (someday) a coherent whole.
I agree that moving docs is a short-term annoyance, but I'm hoping that
it brings a long-term benefit.

> So* I'd suggest having as less markup in those files as possible and if
> it is needed, automate adding the needed markup, as Jon suggested.

Minimal markup is the policy (it's even documented :).  Automating stuff
that can be automated is an area that has definitely not received
enough attention; hopefully some things can be done there in the very
near future.

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 04:06:40PM -0600, Jonathan Corbet wrote:
> Remember that most of our docs are 99% RST even though they were written
> by people who had never even heard of RST.  I really don't think it's a
> big deal - a far smaller cognitive load than trying to keep up with any
> given subsystem's variable-declaration-ordering rules, for example :)

Tztztz, this thing seems to have hit a nerve with people. Which means, I
will enforce that even more now so that I annoy submitters more! :-P

See, I can do my own "RST" too. :-P

Srsly: ok, good. Sounds like we're on the same page then.

>  I'm trying to do the same in Documentation/, with an attempt to be
> sympathetic toward our readers, sort things by intended audience,
> and create (someday) a coherent whole. I agree that moving docs is
> a short-term annoyance, but I'm hoping that it brings a long-term
> benefit.

Ok, that's fair. I've been moving files too, in the past.

> Minimal markup is the policy (it's even documented :).  Automating stuff
> that can be automated is an area that has definitely not received
> enough attention; hopefully some things can be done there in the very
> near future.

Sounds nice, thanks Jon!

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 11:38:16PM +0200, Borislav Petkov wrote:
> If that is all the changes it would need, then I guess that's ok. Btw,
> those rst-conversion patches don't really show what got changed. Dunno
> if git can even show that properly. I diffed the two files by hand to
> see what got changed, see end of mail.

That is not a happy diff; that table has gotten waay worse to read due
to all that extra table crap.

> ---
> --- mm.old	2019-04-23 23:18:55.954335784 +0200
> +++ mm.new	2019-04-23 23:18:48.122335821 +0200
> @@ -18,51 +18,68 @@ Notes:
>     notation than "16 EB", which few will recognize at first sight as 16 exabytes.
>     It also shows it nicely how incredibly large 64-bit address space is.
>  
> -========================================================================================================================
> -    Start addr    |   Offset   |     End addr     |  Size   | VM area description
> -========================================================================================================================
> -                  |            |                  |         |
> - 0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm
> -__________________|____________|__________________|_________|___________________________________________________________
> -                  |            |                  |         |
> - 0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
> -                  |            |                  |         |     virtual memory addresses up to the -128 TB
> -                  |            |                  |         |     starting offset of kernel mappings.
> -__________________|____________|__________________|_________|___________________________________________________________
> -                                                            |
> -                                                            | Kernel-space virtual memory, shared between all processes:
> -____________________________________________________________|___________________________________________________________
> -                  |            |                  |         |
> - ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor
> - ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI
> - ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)
> - ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole
> - ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)
> - ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole
> - ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)
> - ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole
> - ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory
> -__________________|____________|__________________|_________|____________________________________________________________
> -                                                            |
> -                                                            | Identical layout to the 56-bit one from here on:
> -____________________________________________________________|____________________________________________________________
> -                  |            |                  |         |
> - fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
> -                  |            |                  |         | vaddr_end for KASLR
> - fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
> - fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
> - ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
> - ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
> - ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
> - ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
> - ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
> - ffffffff80000000 |-2048    MB |                  |         |
> - ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
> - ffffffffff000000 |  -16    MB |                  |         |
> -    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
> - ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
> - ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
> -__________________|____________|__________________|_________|___________________________________________________________
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
> ++=================+============+==================+=========+===========================================================+
> +|                 |            |                  |         |                                                           |
> +|0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm               |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                 |            |                  |         |                                                           |
> +|0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical       |
> +|                 |            |                  |         | virtual memory addresses up to the -128 TB                |
> +|                 |            |                  |         | starting offset of kernel mappings.                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                      **Kernel-space virtual memory, shared between all processes:**                                   |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor              |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI                                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)  |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)                      |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                         **Identical layout to the 56-bit one from here on:**                                          |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
> +|                 |            |                  |         | vaddr_end for KASLR                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff80000000 |-2048    MB |                  |         |                                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffff000000 |  -16    MB |                  |         |                                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Wed, 24 Apr 2019 08:52:09 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 11:38:16PM +0200, Borislav Petkov wrote:
> > If that is all the changes it would need, then I guess that's ok. Btw,
> > those rst-conversion patches don't really show what got changed. Dunno
> > if git can even show that properly. I diffed the two files by hand to
> > see what got changed, see end of mail.  
> 
> That is not a happy diff; that table has gotten waay worse to read due
> to all that extra table crap.

Not that I'm proposing such change, but, as a reference, I just discovered 
today that there's a way to make it even lighter than it is while still
showing it as a table:

=================  ======== ==   ================  ===== ==  ===========================================================
    Start addr        Offset        End addr         Size    VM area description
-----------------  -----------   ----------------  --------  -----------------------------------------------------------
 0000000000000000      0         00007fffffffffff    128 TB   user-space virtual memory, different per mm

 0000800000000000   +128    TB   ffff7fffffffffff   ~16M TB   ... huge, almost 64 bits wide hole of non-canonical
                                                                  virtual memory addresses up to the -128 TB
                                                                  starting offset of kernel mappings.

-----------------  -------- --   ----------------  ----- --  -----------------------------------------------------------
-                                                            Kernel-space virtual memory, shared between all processes:
-----------------  -----------   ----------------  --------  -----------------------------------------------------------

 ffff800000000000   -128    TB   ffff87ffffffffff      8 TB   ... guard hole, also reserved for hypervisor
 ffff880000000000   -120    TB   ffff887fffffffff    0.5 TB   LDT remap for PTI
 ffff888000000000   -119.5  TB   ffffc87fffffffff     64 TB   direct mapping of all physical memory (page_offset_base)
 ffffc88000000000    -55.5  TB   ffffc8ffffffffff    0.5 TB   ... unused hole
 ffffc90000000000    -55    TB   ffffe8ffffffffff     32 TB   vmalloc/ioremap space (vmalloc_base)
 ffffe90000000000    -23    TB   ffffe9ffffffffff      1 TB   ... unused hole
 ffffea0000000000    -22    TB   ffffeaffffffffff      1 TB   virtual memory map (vmemmap_base)
 ffffeb0000000000    -21    TB   ffffebffffffffff      1 TB   ... unused hole
 ffffec0000000000    -20    TB   fffffbffffffffff     16 TB   KASAN shadow memory
-----------------  -------- --   ----------------  ----- --  -----------------------------------------------------------
-                                                            Identical layout to the 56-bit one from here on:
-----------------  -----------   ----------------  --------  -----------------------------------------------------------

 fffffc0000000000     -4    TB   fffffdffffffffff      2 TB   ... unused hole
                                                              vaddr_end for KASLR
 fffffe0000000000     -2    TB   fffffe7fffffffff    0.5 TB   cpu_entry_area mapping
 fffffe8000000000     -1.5  TB   fffffeffffffffff    0.5 TB   ... unused hole
 ffffff0000000000     -1    TB   ffffff7fffffffff    0.5 TB   %esp fixup stacks
 ffffff8000000000   -512    GB   ffffffeeffffffff    444 GB   ... unused hole
 ffffffef00000000    -68    GB   fffffffeffffffff     64 GB   EFI region mapping space
 ffffffff00000000     -4    GB   ffffffff7fffffff      2 GB   ... unused hole
 ffffffff80000000     -2    GB   ffffffff9fffffff    512 MB   kernel text mapping, mapped to physical address 0
 ffffffff80000000  -2048    MB
 ffffffffa0000000  -1536    MB   fffffffffeffffff   1520 MB   module mapping space
 ffffffffff000000    -16    MB
    FIXADDR_START   ~-11    MB   ffffffffff5fffff   ~0.5 MB   kernel-internal fixmap range, variable size and offset
 ffffffffff600000    -10    MB   ffffffffff600fff      4 kB   legacy vsyscall ABI
 ffffffffffe00000     -2    MB   ffffffffffffffff      2 MB   ... unused hole
=================  ======== ==   ================  ===== ==  ===========================================================

If one wants the table headers as such, an extra line is required:


=================  ======== ==   ================  ===== ==  ===========================================================
    Start addr        Offset        End addr         Size    VM area description
-----------------  -----------   ----------------  --------  -----------------------------------------------------------
=================  ======== ==   ================  ===== ==  ===========================================================

<snip/>

=================  ======== ==   ================  ===== ==  ===========================================================


The output using this approach and a markup to use mono-spaced cells
e. g. either using ..raw or using .. cssclass as commented before in
this thread is at:

	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm_alternative.html

Just converted the first table, keeping the other as a literal block.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 05:05:02PM -0300, Mauro Carvalho Chehab wrote:
> > That's my view about how that specific file would be after
> > converted to ReST:
> > 
> > 	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames
> > 
> > I don't have any troubles reading/understanding it as a plain text
> > file,  
> 
> If that is all the changes it would need, then I guess that's ok. Btw,
> those rst-conversion patches don't really show what got changed. Dunno
> if git can even show that properly. I diffed the two files by hand to
> see what got changed, see end of mail.

Well, you can use git show -M01 and it will likely show what
changed. The thing is that plain diff is not very good showing
diffs on text files. I suspect that using some tool like wdiff
would give a better view of such changes.

> So I guess if table in rst means, one needs to draw rows and columns, I
> guess that's ok. It's not like I have to do it every day.

Yes, for complex tables, one needs to draw rows/columns. For simple
tables, all you need to do is something like:

  ====== ========   ====    ========    ===
  -      CONT PTE    PMD    CONT PMD    PUD
  ====== ========   ====    ========    ===
  4K:         64K     2M         32M     1G
  16K:         2M    32M          1G
  64K:         2M   512M         16G
  ====== ========   ====    ========    ===

in order to teach Sphinx where each column starts/stops, and
(optionally) show the table titles in bold.

(that's from Documentation/arm64/hugetlbpage.rst conversion)

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Yeah, one has to take the conversion effort, but once done, it should be
easy to keep it updated.

> > and its html output is also nice (although Sphinx 1.7.8 seems to
> > have some issues when parsing some cells - probably due to some bug):
> > 
> > 	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html  
> 
> I don't know how that looks in your browser but in mine those addresses
> are not in monospaced font and there's no properly reading them.
> 
> And yap, the cells parsing fun I see too.

Font selection is one of the things would require some markup, as a
plain text file doesn't have font changes.

There are several ways to make it use a monospaced font.

The straight forward way would be to place everything that it is
monospaced inside ``double quotes``, with is the ReST way to mark
a literal block inside a text. IMHO, that would add too much
"noise" at the tables.

Another possibility would be to do:

	.. raw:: html

	       <head><style>td { font-family: monospace, monospace; }</style></head>

(the double monospace here is not a mistake - it is due to a known
bug^H^H^Hfeature on some browsers[1])

[1] https://stackoverflow.com/questions/38781089/font-family-monospace-monospace

IMO, the best alternative would be to add a new class to the css file,
and use it whenever we need a table with monospaced font, e. g.:

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index e21e36cd6761..0948de6651f8 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -125,3 +125,7 @@ div[class^="highlight"] pre {
         color: inherit;
     }
 }
+
+table.monospaced {
+	font-family: monospace, monospace;
+}
diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst
index e8a92fa0f9b2..704bad5c5130 100644
--- a/Documentation/x86/x86_64/mm.rst
+++ b/Documentation/x86/x86_64/mm.rst
@@ -18,6 +18,8 @@ Notes:
    notation than "16 EB", which few will recognize at first sight as 16 exabytes.
    It also shows it nicely how incredibly large 64-bit address space is.
 
+.. cssclass:: monospaced
+
 +-----------------+------------+------------------+---------+-----------------------------------------------------------+
 |   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
 +=================+============+==================+=========+===========================================================+

(patch on the top of this tree
https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames)

The ..cssclass:: markup on the above example will be applied just to
the table below it. So, with that, it is possible to have normal and
monospaced tables mixed (if you apply the above patch, you'll see
that just the first table will use monospaced fonts).

- 

Personally, I don't care much with monospaced fonts on this table. After
all, if I want to see it monospaced, I can simply click at the
"View page source" at the browser, and it will display the file as a
plain old monospaced text file.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Wed, Apr 24, 2019 at 07:40:07AM -0300, Mauro Carvalho Chehab wrote:
> Personally, I don't care much with monospaced fonts on this table. After
> all, if I want to see it monospaced, I can simply click at the
> "View page source" at the browser, and it will display the file as a
> plain old monospaced text file.

Goes to show why kernel people wouldn't want to look at that in
the browser. Long hex numbers are hard to read as it is - that's
why there's even the 4-digit separator in some docs, for example:
0xffff_ffff_8100_0000.

Not having it monospaced makes the whole thing even less readable.

That's why it is important for the markup not to get in the way of
people looking at those files in an editor.

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Wed, 24 Apr 2019 16:54:10 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Wed, Apr 24, 2019 at 07:40:07AM -0300, Mauro Carvalho Chehab wrote:
> > Personally, I don't care much with monospaced fonts on this table. After
> > all, if I want to see it monospaced, I can simply click at the
> > "View page source" at the browser, and it will display the file as a
> > plain old monospaced text file.  
> 
> Goes to show why kernel people wouldn't want to look at that in
> the browser. Long hex numbers are hard to read as it is - that's
> why there's even the 4-digit separator in some docs, for example:
> 0xffff_ffff_8100_0000.

IMHO, even the 0x and _ would make it harder to read. This is a way
more easy for my eyes:

	ffff ffff 8100 0000

> Not having it monospaced makes the whole thing even less readable.

Yeah, I see your point and agree with it.

Just saying that, if all I want is to check if addresses that start
with ffff80 belongs to the guard hole, or just to copy a value from 
a table into some C code, the font doesn't matter much, and, if
I care, a simple click would show it in monospaced fonts.

Looking from your PoV, something like:


|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |


is very hard to be parsed by a human eye, even with monospaced fonts.
In order to make it easier, I would replace it by:

|ffff ffff 8000 0000 |   -2    GB | ffff ffff 9fff ffff |  512 MB | kernel text mapping, mapped to physical address 0         |


> 
> That's why it is important for the markup not to get in the way of
> people looking at those files in an editor.

Fully agreed. the markups should make things easier and not
harder for people to read its contents.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 19:11:58 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> When writing, I now have to be bothered about this format crap over just
> trying to write a coherent document.

Just write text, it'll all work out in the end :)

> Look at crap like this:
> 
> "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> :c:func:`kmem_cache_alloc` and"
> 
> That should've been written like:
> 
> "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> and"

Yeah, I get it.  That markup generates cross-references, which can be
seriously useful for readers - we want that.  But I do wonder if we
couldn't do it automatically with just a little bit of scripting work.
It's not to hard to recognize this_is_a_function(), after all.  I'll look
into that, it would definitely help to remove some gunk from the source
docs.

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 11:53:49AM -0600, Jonathan Corbet wrote:
> > Look at crap like this:
> > 
> > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> > :c:func:`kmem_cache_alloc` and"
> > 
> > That should've been written like:
> > 
> > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> > and"
> 
> Yeah, I get it.  That markup generates cross-references, which can be
> seriously useful for readers - we want that.

The funny thing is; that sentence continues (on a new line) like:

"friends are traced and the pointers, together with additional"

So while it then has cross-references to a few functions, all 'friends'
are left dangling. So what's the point of the cross-references?

Also, 'make ctags' and follow tag (ctrl-] for fellow vim users) will get
you to the function, no magic markup required.

> But I do wonder if we
> couldn't do it automatically with just a little bit of scripting work.
> It's not to hard to recognize this_is_a_function(), after all.  I'll look
> into that, it would definitely help to remove some gunk from the source
> docs.

That would be good; less markup is more.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 11:53:49 -0600
Jonathan Corbet <corbet-T1hC0tSOHrs@public.gmane.org> escreveu:

> On Tue, 23 Apr 2019 19:11:58 +0200
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 

> > Look at crap like this:
> > 
> > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> > :c:func:`kmem_cache_alloc` and"
> > 
> > That should've been written like:
> > 
> > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> > and"  
> 
> Yeah, I get it.  That markup generates cross-references, which can be
> seriously useful for readers - we want that.  But I do wonder if we
> couldn't do it automatically with just a little bit of scripting work.
> It's not to hard to recognize this_is_a_function(), after all.  I'll look
> into that, it would definitely help to remove some gunk from the source
> docs.

While on it, one thing that I noticed on several documents is that
they reference other documents by their names. On this conversion,
I avoided replacing that by a :ref:`` tag or a :doc:`` tag. I only
added cross references on two cases:

	- a latex file that got converted to ReST and had such
	  cross-references already;

	- one of the document sets that seemed to be using some other
	  markup language very close to ReST, but with a different
	  cross-reference markup. So, I just converted it to use
	  the syntax that Sphinx would recognize.

Anyway, one of the things that occurred to me is that maybe
some scripting work or a ReST extension could do something to parse
"Documentation/foo" as :doc:`Documentation/foo` without needing to 
explicitly use any ReST specific tags.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 17:19:44 -0300
Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

> Anyway, one of the things that occurred to me is that maybe
> some scripting work or a ReST extension could do something to parse
> "Documentation/foo" as :doc:`Documentation/foo` without needing to 
> explicitly use any ReST specific tags.

That probably makes sense too.  People do want to link to specific
subsections within documents, though; maybe we could allow
"Documentation/foo#bar" for that.  Such "markup" could even be useful for
people reading the plain-text files.

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Wes Turner]

[-- Attachment #1: Type: text/plain, Size: 6607 bytes --]

- Accessible, usable docs are worth something in ROI
  - https://www.writethedocs.org/
  - https://read-the-docs.readthedocs.io/en/latest/
  -
https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
    - Dockerfile that extends from readthedocs/build:latest (which has the
GBs of latex necessary to run `make latexpdf` for all you PDF lovers out
there)

- https://github.com/yoloseem/awesome-sphinxdoc
  - There are various Sphinx extensions for optionally including generated
API docs for various languages
  - If you add the extensions you want installed to your requirements.txt
or environment.yml, ReadTheDocs will install those for every build. You can
also create (and maintain) a custom Docker image with all of the docs
building dependencies installed (e.g. requirements_dev.txt and/or
docs/requirements.txt)

- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
  - This says "Copyright 2016"? That's set in conf.py

I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils

I'll just CC those sections here:

```rst

.. index:: Docutils
.. _docutils:

Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs:
https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk

Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.

.. index:: Sphinx
.. _sphinx:

Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<
https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc


Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.

Sphinx extends :ref:`Docutils` with a number of useful markup behaviors
which are not supported by other ReStructuredText parsers.

Most other ReStructuredText parsers do not support Sphinx directives;
so, for example,

* GitHub and BitBucket do not support Sphinx but do support ReStructuredText
  so ``README.rst`` containing Sphinx tags renders in plaintext or raises
errors.

  For example, the index page of this
  :ref:`Sphinx` documentation set is generated from
  a file named ``index.rst`` that referenced by ``docs/conf.py``,
  which is utilized by ``sphinx-build`` in the ``Makefile``.

  * Input:

    .. code:: bash

      _indexrst="$WORKON_HOME/src/westurner/tools/index.rst"
      e $_indexrst

      # with westurner/dotfiles.venv
      mkvirtualenv westurner
      we westurner tools; mkdir -p $_SRC
      git clone ssh://git@github.com/westurner/tools
      cdw; e index.rst    # ew index.rst

    https://github.com/westurner/tools/blob/master/index.rst

    https://raw.githubusercontent.com/westurner/tools/master/index.rst



  * Output:

    .. code:: bash

      cd $_WRD                        # cdwrd; cdw
      git status; make <tab>          # gitw status; makew <tab>
      make html singlehtml            # make docs
      web ./_build/html/index.html    # make open

      make gh-pages       # ghp-import -n -p ./_build/html/ -b gh-pages
      make push           # gitw push <origin> <destbranch>

    https://github.com/westurner/tools/blob/gh-pages/index.html

    https://westurner.github.io/tools/


    * RawGit:

      dev/test: https://rawgit.com/westurner/tools/gh-pages/index.html

      CDN: https://cdn.rawgit.com/westurner/tools/gh-pages/index.html

  * Output: *ReadTheDocs*:

    https://<projectname>.readthedocs.io/en/<version>/

    https://read-the-docs.readthedocs.io/en/latest/


.. glossary::

   Sphinx Builder
      A Sphinx Builder transforms :ref:`ReStructuredText` into various
      output forms:

         * HTML
         * LaTeX
         * PDF
         * ePub
         * MOBI
         * JSON
         * OpenDocument (OpenOffice)
         * Office Open XML (MS Word)

      See: `Sphinx Builders <http://sphinx-doc.org/builders.html>`_

   Sphinx ReStructuredText
      Sphinx extends :ref:`ReStructuredText` with roles and directives
      which only work with Sphinx.

   Sphinx Directive
      Sphinx extensions of :ref:`Docutils` :ref:`ReStructuredText`
directives.

      Most other ReStructuredText parsers do not support Sphinx directives.

      .. code-block:: rest

         .. toctree::

            readme
            installation
            usage

      See: `Sphinx Directives <http://sphinx-doc.org/rest.html#directives>`_

   Sphinx Role
      Sphinx extensions of :ref:`Docutils` :ref:`RestructuredText` roles

      Most other ReStructuredText parsers do not support Sphinx directives.

      .. code-block:: rest

            .. _anchor-name:

            A link to :ref:`anchor <anchor-name>`.

```

On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
>
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.  More readable docs should
> lead to more educated developers who understand the code better.  More
> writable docs will bring more people in to help to improve them.  The
> former effect has been reported in the GPU community, where they say that
> the quality of submissions has improved along with the docs.  The latter
> can be observed in the increased number of people working on the docs
> overall, something that Linus noted in the 5.1-rc1 announcement.
>
> Hopefully that's worth something :)
>
> Thanks,
>
> jon
>

[-- Attachment #2: Type: text/html, Size: 10658 bytes --]

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Wes Turner]

[-- Attachment #1: Type: text/plain, Size: 4606 bytes --]

- Accessible, usable docs are worth something in ROI
  - https://www.writethedocs.org/
  - https://read-the-docs.readthedocs.io/en/latest/
  -
https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
    - Dockerfile that extends from readthedocs/build:latest (which has the
GBs of latex necessary to run `make latexpdf` for all you PDF lovers out
there)

- https://github.com/yoloseem/awesome-sphinxdoc
  - There are various Sphinx extensions for optionally including generated
API docs for various languages
  - If you add the extensions you want installed to your requirements.txt
or environment.yml, ReadTheDocs will install those for every build. You can
also create (and maintain) a custom Docker image with all of the docs
building dependencies installed (e.g. requirements_dev.txt and/or
docs/requirements.txt)

- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
  - This says "Copyright 2016"? That's set in conf.py

I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils

I'll just CC those sections here
wrapped in a Markdown fenced code block

```rst

.. index:: Docutils
.. _docutils:

Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs:
https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk

Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.


.. index:: Sphinx
.. _sphinx:

Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<
https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc

Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.

[...]

```

FWIW, ReadTheDocs can host multiple versions of the docs according to the
repo
tags you specify in the web admin.
There may be a way to use the RTD JS UI for selecting versions
with the docs hosted on your own server?
Such as https://www.kernel.org/doc/html/latest/

- https://github.com/torvalds/linux/blob/master/Documentation/conf.py
- https://github.com/torvalds/linux/blob/master/Documentation/Makefile

-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst
-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst
-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst

- https://www.kernel.org/doc/html/latest/
- https://www.kernel.org/doc/html/latest/doc-guide/
-
https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install
-
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments


On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
>
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.  More readable docs should
> lead to more educated developers who understand the code better.  More
> writable docs will bring more people in to help to improve them.  The
> former effect has been reported in the GPU community, where they say that
> the quality of submissions has improved along with the docs.  The latter
> can be observed in the increased number of people working on the docs
> overall, something that Linus noted in the 5.1-rc1 announcement.
>
> Hopefully that's worth something :)
>
> Thanks,
>
> jon
>

[-- Attachment #2: Type: text/html, Size: 7705 bytes --]