[PATCH 00/29] Standardize doc formats - part 3

[PATCH 00/29] Standardize doc formats - part 3

[Mauro Carvalho Chehab]

Each document under Documentation/*.txt has its own format.
Some follow markup notations, some don't even have a title!

In order to try to get some order on it, change the document
style to the standard we're adopting after the adoption of
ReStructured Text.

The documents touched on this series now build fine with
Sphinx, if renamed to *.rst extension.

The main goal with this is to teach people by example about
what format is expected on newer documents. It also helps
to add those files to Kernel books.

In order to make things more palatable, I'm spliting the
conversion into three parts.

This is	part 3.

Mauro Carvalho Chehab (29):
  pinctrl.txt: standardize document format
  pnp.txt: standardize document format
  preempt-locking.txt: standardize document format
  printk-formats.txt: standardize document format
  pwm.txt: standardize document format
  rbtree.txt: standardize document format
  remoteproc.txt: standardize document format
  rfkill.txt: standardize document format
  robust-futex-ABI.txt: standardize document format
  robust-futexes.txt: standardize document format
  rpmsg.txt: standardize document format
  rtc.txt: standardize document format
  SAK.txt: standardize document format
  sgi-ioc4.txt: standardize document format
  siphash.txt: standardize document format
  SM501.txt: standardize document format
  smsc_ece1099.txt: standardize document format
  static-keys.txt: standardize document format
  svga.txt: standardize document format
  sync_file.txt: standardize document format
  this_cpu_ops.txt: standardize document format
  unaligned-memory-access.txt: standardize document format
  vfio-mediated-device.txt: standardize document format
  vfio.txt: standardize document format
  video-output.txt: standardize document format
  xillybus.txt: standardize document format
  xz.txt: standardize document format
  zorro.txt: standardize document format
  dell_rbu.txt: standardize document format

 Documentation/SAK.txt                     |   65 +-
 Documentation/SM501.txt                   |    9 +-
 Documentation/dell_rbu.txt                |   81 ++-
 Documentation/pinctrl.txt                 | 1104 +++++++++++++++--------------
 Documentation/pnp.txt                     |  343 +++++----
 Documentation/preempt-locking.txt         |   40 +-
 Documentation/printk-formats.txt          |  416 ++++++-----
 Documentation/pwm.txt                     |   46 +-
 Documentation/rbtree.txt                  |   88 +--
 Documentation/remoteproc.txt              |  320 +++++----
 Documentation/rfkill.txt                  |   47 +-
 Documentation/robust-futex-ABI.txt        |   14 +-
 Documentation/robust-futexes.txt          |   12 +-
 Documentation/rpmsg.txt                   |  340 +++++----
 Documentation/rtc.txt                     |   44 +-
 Documentation/sgi-ioc4.txt                |    4 +
 Documentation/siphash.txt                 |  186 ++---
 Documentation/smsc_ece1099.txt            |    4 +
 Documentation/static-keys.txt             |  199 +++---
 Documentation/svga.txt                    |  146 ++--
 Documentation/sync_file.txt               |   23 +-
 Documentation/this_cpu_ops.txt            |   49 +-
 Documentation/unaligned-memory-access.txt |   57 +-
 Documentation/vfio-mediated-device.txt    |  252 +++----
 Documentation/vfio.txt                    |  261 +++----
 Documentation/video-output.txt            |   54 +-
 Documentation/xillybus.txt                |   29 +-
 Documentation/xz.txt                      |  182 ++---
 Documentation/zorro.txt                   |   59 +-
 29 files changed, 2437 insertions(+), 2037 deletions(-)

-- 
2.9.4

[PATCH 00/29] Standardize doc formats - part 3

[Mauro Carvalho Chehab]

Each document under Documentation/*.txt has its own format.
Some follow markup notations, some don't even have a title!

In order to try to get some order on it, change the document
style to the standard we're adopting after the adoption of
ReStructured Text.

The documents touched on this series now build fine with
Sphinx, if renamed to *.rst extension.

The main goal with this is to teach people by example about
what format is expected on newer documents. It also helps
to add those files to Kernel books.

In order to make things more palatable, I'm spliting the
conversion into three parts.

This is	part 3.

Mauro Carvalho Chehab (29):
  pinctrl.txt: standardize document format
  pnp.txt: standardize document format
  preempt-locking.txt: standardize document format
  printk-formats.txt: standardize document format
  pwm.txt: standardize document format
  rbtree.txt: standardize document format
  remoteproc.txt: standardize document format
  rfkill.txt: standardize document format
  robust-futex-ABI.txt: standardize document format
  robust-futexes.txt: standardize document format
  rpmsg.txt: standardize document format
  rtc.txt: standardize document format
  SAK.txt: standardize document format
  sgi-ioc4.txt: standardize document format
  siphash.txt: standardize document format
  SM501.txt: standardize document format
  smsc_ece1099.txt: standardize document format
  static-keys.txt: standardize document format
  svga.txt: standardize document format
  sync_file.txt: standardize document format
  this_cpu_ops.txt: standardize document format
  unaligned-memory-access.txt: standardize document format
  vfio-mediated-device.txt: standardize document format
  vfio.txt: standardize document format
  video-output.txt: standardize document format
  xillybus.txt: standardize document format
  xz.txt: standardize document format
  zorro.txt: standardize document format
  dell_rbu.txt: standardize document format

 Documentation/SAK.txt                     |   65 +-
 Documentation/SM501.txt                   |    9 +-
 Documentation/dell_rbu.txt                |   81 ++-
 Documentation/pinctrl.txt                 | 1104 +++++++++++++++--------------
 Documentation/pnp.txt                     |  343 +++++----
 Documentation/preempt-locking.txt         |   40 +-
 Documentation/printk-formats.txt          |  416 ++++++-----
 Documentation/pwm.txt                     |   46 +-
 Documentation/rbtree.txt                  |   88 +--
 Documentation/remoteproc.txt              |  320 +++++----
 Documentation/rfkill.txt                  |   47 +-
 Documentation/robust-futex-ABI.txt        |   14 +-
 Documentation/robust-futexes.txt          |   12 +-
 Documentation/rpmsg.txt                   |  340 +++++----
 Documentation/rtc.txt                     |   44 +-
 Documentation/sgi-ioc4.txt                |    4 +
 Documentation/siphash.txt                 |  186 ++---
 Documentation/smsc_ece1099.txt            |    4 +
 Documentation/static-keys.txt             |  199 +++---
 Documentation/svga.txt                    |  146 ++--
 Documentation/sync_file.txt               |   23 +-
 Documentation/this_cpu_ops.txt            |   49 +-
 Documentation/unaligned-memory-access.txt |   57 +-
 Documentation/vfio-mediated-device.txt    |  252 +++----
 Documentation/vfio.txt                    |  261 +++----
 Documentation/video-output.txt            |   54 +-
 Documentation/xillybus.txt                |   29 +-
 Documentation/xz.txt                      |  182 ++---
 Documentation/zorro.txt                   |   59 +-
 29 files changed, 2437 insertions(+), 2037 deletions(-)

-- 
2.9.4


-- 
You received this message because you are subscribed to "rtc-linux".
Membership options at http://groups.google.com/group/rtc-linux .
Please read http://groups.google.com/group/rtc-linux/web/checklist
before submitting a driver.
--- 
You received this message because you are subscribed to the Google Groups "rtc-linux" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rtc-linux+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit https://groups.google.com/d/optout.

[PATCH 01/29] pinctrl.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx.

This document is almost following the standard stile.

There are only two things to adjust on it:

- promote the level of the document title;
- mark literal blocks as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/pinctrl.txt | 1104 +++++++++++++++++++++++----------------------
 1 file changed, 560 insertions(+), 544 deletions(-)

diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt
index f2af35f6d6b2..bc1eb2ca3342 100644
--- a/Documentation/pinctrl.txt
+++ b/Documentation/pinctrl.txt
@@ -1,4 +1,7 @@
+===============================
 PINCTRL (PIN CONTROL) subsystem
+===============================
+
 This document outlines the pin control subsystem in Linux
 
 This subsystem deals with:
@@ -33,7 +36,7 @@ When a PIN CONTROLLER is instantiated, it will register a descriptor to the
 pin control framework, and this descriptor contains an array of pin descriptors
 describing the pins handled by this specific pin controller.
 
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
 
         A   B   C   D   E   F   G   H
 
@@ -54,39 +57,40 @@ Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
    1    o   o   o   o   o   o   o   o
 
 To register a pin controller and name all the pins on this package we can do
-this in our driver:
+this in our driver::
 
-#include <linux/pinctrl/pinctrl.h>
+	#include <linux/pinctrl/pinctrl.h>
 
-const struct pinctrl_pin_desc foo_pins[] = {
-      PINCTRL_PIN(0, "A8"),
-      PINCTRL_PIN(1, "B8"),
-      PINCTRL_PIN(2, "C8"),
-      ...
-      PINCTRL_PIN(61, "F1"),
-      PINCTRL_PIN(62, "G1"),
-      PINCTRL_PIN(63, "H1"),
-};
+	const struct pinctrl_pin_desc foo_pins[] = {
+	PINCTRL_PIN(0, "A8"),
+	PINCTRL_PIN(1, "B8"),
+	PINCTRL_PIN(2, "C8"),
+	...
+	PINCTRL_PIN(61, "F1"),
+	PINCTRL_PIN(62, "G1"),
+	PINCTRL_PIN(63, "H1"),
+	};
 
-static struct pinctrl_desc foo_desc = {
-	.name = "foo",
-	.pins = foo_pins,
-	.npins = ARRAY_SIZE(foo_pins),
-	.owner = THIS_MODULE,
-};
+	static struct pinctrl_desc foo_desc = {
+		.name = "foo",
+		.pins = foo_pins,
+		.npins = ARRAY_SIZE(foo_pins),
+		.owner = THIS_MODULE,
+	};
 
-int __init foo_probe(void)
-{
-	int error;
+	int __init foo_probe(void)
+	{
+		int error;
 
-	struct pinctrl_dev *pctl;
+		struct pinctrl_dev *pctl;
 
-	error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl);
-	if (error)
-		return error;
+		error = pinctrl_register_and_init(&foo_desc, <PARENT>,
+						  NULL, &pctl);
+		if (error)
+			return error;
 
-	return pinctrl_enable(pctl);
-}
+		return pinctrl_enable(pctl);
+	}
 
 To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
 selected drivers, you need to select them from your machine's Kconfig entry,
@@ -105,7 +109,7 @@ the pin controller.
 
 For a padring with 467 pads, as opposed to actual pins, I used an enumeration
 like this, walking around the edge of the chip, which seems to be industry
-standard too (all these pads had names, too):
+standard too (all these pads had names, too)::
 
 
      0 ..... 104
@@ -128,64 +132,64 @@ on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
 on { 24, 25 }.
 
 These two groups are presented to the pin control subsystem by implementing
-some generic pinctrl_ops like this:
-
-#include <linux/pinctrl/pinctrl.h>
-
-struct foo_group {
-	const char *name;
-	const unsigned int *pins;
-	const unsigned num_pins;
-};
-
-static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
-static const unsigned int i2c0_pins[] = { 24, 25 };
+some generic pinctrl_ops like this::
+
+	#include <linux/pinctrl/pinctrl.h>
+
+	struct foo_group {
+		const char *name;
+		const unsigned int *pins;
+		const unsigned num_pins;
+	};
+
+	static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
+	static const unsigned int i2c0_pins[] = { 24, 25 };
+
+	static const struct foo_group foo_groups[] = {
+		{
+			.name = "spi0_grp",
+			.pins = spi0_pins,
+			.num_pins = ARRAY_SIZE(spi0_pins),
+		},
+		{
+			.name = "i2c0_grp",
+			.pins = i2c0_pins,
+			.num_pins = ARRAY_SIZE(i2c0_pins),
+		},
+	};
+
+
+	static int foo_get_groups_count(struct pinctrl_dev *pctldev)
+	{
+		return ARRAY_SIZE(foo_groups);
+	}
 
-static const struct foo_group foo_groups[] = {
+	static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+					unsigned selector)
 	{
-		.name = "spi0_grp",
-		.pins = spi0_pins,
-		.num_pins = ARRAY_SIZE(spi0_pins),
-	},
+		return foo_groups[selector].name;
+	}
+
+	static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+				const unsigned **pins,
+				unsigned *num_pins)
 	{
-		.name = "i2c0_grp",
-		.pins = i2c0_pins,
-		.num_pins = ARRAY_SIZE(i2c0_pins),
-	},
-};
-
-
-static int foo_get_groups_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_groups);
-}
-
-static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
-				       unsigned selector)
-{
-	return foo_groups[selector].name;
-}
-
-static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
-			       const unsigned **pins,
-			       unsigned *num_pins)
-{
-	*pins = (unsigned *) foo_groups[selector].pins;
-	*num_pins = foo_groups[selector].num_pins;
-	return 0;
-}
-
-static struct pinctrl_ops foo_pctrl_ops = {
-	.get_groups_count = foo_get_groups_count,
-	.get_group_name = foo_get_group_name,
-	.get_group_pins = foo_get_group_pins,
-};
-
-
-static struct pinctrl_desc foo_desc = {
-       ...
-       .pctlops = &foo_pctrl_ops,
-};
+		*pins = (unsigned *) foo_groups[selector].pins;
+		*num_pins = foo_groups[selector].num_pins;
+		return 0;
+	}
+
+	static struct pinctrl_ops foo_pctrl_ops = {
+		.get_groups_count = foo_get_groups_count,
+		.get_group_name = foo_get_group_name,
+		.get_group_pins = foo_get_group_pins,
+	};
+
+
+	static struct pinctrl_desc foo_desc = {
+	...
+	.pctlops = &foo_pctrl_ops,
+	};
 
 The pin control subsystem will call the .get_groups_count() function to
 determine the total number of legal selectors, then it will call the other functions
@@ -213,62 +217,62 @@ The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
 above, is entirely defined by the pin controller driver.
 
 The pin configuration driver implements callbacks for changing pin
-configuration in the pin controller ops like this:
+configuration in the pin controller ops like this::
 
-#include <linux/pinctrl/pinctrl.h>
-#include <linux/pinctrl/pinconf.h>
-#include "platform_x_pindefs.h"
+	#include <linux/pinctrl/pinctrl.h>
+	#include <linux/pinctrl/pinconf.h>
+	#include "platform_x_pindefs.h"
 
-static int foo_pin_config_get(struct pinctrl_dev *pctldev,
-		    unsigned offset,
-		    unsigned long *config)
-{
-	struct my_conftype conf;
+	static int foo_pin_config_get(struct pinctrl_dev *pctldev,
+			unsigned offset,
+			unsigned long *config)
+	{
+		struct my_conftype conf;
 
-	... Find setting for pin @ offset ...
+		... Find setting for pin @ offset ...
 
-	*config = (unsigned long) conf;
-}
+		*config = (unsigned long) conf;
+	}
 
-static int foo_pin_config_set(struct pinctrl_dev *pctldev,
-		    unsigned offset,
-		    unsigned long config)
-{
-	struct my_conftype *conf = (struct my_conftype *) config;
+	static int foo_pin_config_set(struct pinctrl_dev *pctldev,
+			unsigned offset,
+			unsigned long config)
+	{
+		struct my_conftype *conf = (struct my_conftype *) config;
 
-	switch (conf) {
-		case PLATFORM_X_PULL_UP:
-		...
+		switch (conf) {
+			case PLATFORM_X_PULL_UP:
+			...
+			}
 		}
 	}
-}
 
-static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
-		    unsigned selector,
-		    unsigned long *config)
-{
-	...
-}
+	static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
+			unsigned selector,
+			unsigned long *config)
+	{
+		...
+	}
 
-static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
-		    unsigned selector,
-		    unsigned long config)
-{
-	...
-}
+	static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
+			unsigned selector,
+			unsigned long config)
+	{
+		...
+	}
 
-static struct pinconf_ops foo_pconf_ops = {
-	.pin_config_get = foo_pin_config_get,
-	.pin_config_set = foo_pin_config_set,
-	.pin_config_group_get = foo_pin_config_group_get,
-	.pin_config_group_set = foo_pin_config_group_set,
-};
+	static struct pinconf_ops foo_pconf_ops = {
+		.pin_config_get = foo_pin_config_get,
+		.pin_config_set = foo_pin_config_set,
+		.pin_config_group_get = foo_pin_config_group_get,
+		.pin_config_group_set = foo_pin_config_group_set,
+	};
 
-/* Pin config operations are handled by some pin controller */
-static struct pinctrl_desc foo_desc = {
-	...
-	.confops = &foo_pconf_ops,
-};
+	/* Pin config operations are handled by some pin controller */
+	static struct pinctrl_desc foo_desc = {
+		...
+		.confops = &foo_pconf_ops,
+	};
 
 Since some controllers have special logic for handling entire groups of pins
 they can exploit the special whole-group pin control function. The
@@ -296,35 +300,35 @@ controller handles control of a certain GPIO pin. Since a single pin controller
 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
 but internally several GPIO silicon blocks, each modelled as a struct
 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
-like this:
+like this::
 
-struct gpio_chip chip_a;
-struct gpio_chip chip_b;
+	struct gpio_chip chip_a;
+	struct gpio_chip chip_b;
 
-static struct pinctrl_gpio_range gpio_range_a = {
-	.name = "chip a",
-	.id = 0,
-	.base = 32,
-	.pin_base = 32,
-	.npins = 16,
-	.gc = &chip_a;
-};
+	static struct pinctrl_gpio_range gpio_range_a = {
+		.name = "chip a",
+		.id = 0,
+		.base = 32,
+		.pin_base = 32,
+		.npins = 16,
+		.gc = &chip_a;
+	};
 
-static struct pinctrl_gpio_range gpio_range_b = {
-	.name = "chip b",
-	.id = 0,
-	.base = 48,
-	.pin_base = 64,
-	.npins = 8,
-	.gc = &chip_b;
-};
+	static struct pinctrl_gpio_range gpio_range_b = {
+		.name = "chip b",
+		.id = 0,
+		.base = 48,
+		.pin_base = 64,
+		.npins = 8,
+		.gc = &chip_b;
+	};
 
-{
-	struct pinctrl_dev *pctl;
-	...
-	pinctrl_add_gpio_range(pctl, &gpio_range_a);
-	pinctrl_add_gpio_range(pctl, &gpio_range_b);
-}
+	{
+		struct pinctrl_dev *pctl;
+		...
+		pinctrl_add_gpio_range(pctl, &gpio_range_a);
+		pinctrl_add_gpio_range(pctl, &gpio_range_b);
+	}
 
 So this complex system has one pin controller handling two different
 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
@@ -348,25 +352,26 @@ chip b:
 
 The above examples assume the mapping between the GPIOs and pins is
 linear. If the mapping is sparse or haphazard, an array of arbitrary pin
-numbers can be encoded in the range like this:
+numbers can be encoded in the range like this::
 
-static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
+	static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
 
-static struct pinctrl_gpio_range gpio_range = {
-	.name = "chip",
-	.id = 0,
-	.base = 32,
-	.pins = &range_pins,
-	.npins = ARRAY_SIZE(range_pins),
-	.gc = &chip;
-};
+	static struct pinctrl_gpio_range gpio_range = {
+		.name = "chip",
+		.id = 0,
+		.base = 32,
+		.pins = &range_pins,
+		.npins = ARRAY_SIZE(range_pins),
+		.gc = &chip;
+	};
 
 In this case the pin_base property will be ignored. If the name of a pin
 group is known, the pins and npins elements of the above structure can be
 initialised using the function pinctrl_get_group_pins(), e.g. for pin
-group "foo":
+group "foo"::
 
-pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);
+	pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
+			       &gpio_range.npins);
 
 When GPIO-specific functions in the pin control subsystem are called, these
 ranges will be used to look up the appropriate pin controller by inspecting
@@ -405,7 +410,7 @@ we usually mean a way of soldering or wiring the package into an electronic
 system, even though the framework makes it possible to also change the function
 at runtime.
 
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
 
         A   B   C   D   E   F   G   H
       +---+
@@ -519,12 +524,12 @@ Definitions:
   In the example case we can define that this particular machine shall
   use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
   fi2c0 group gi2c0, on the primary pin controller, we get mappings
-  like these:
+  like these::
 
-  {
-    {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
-    {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
-  }
+	{
+		{"map-spi0", spi0, pinctrl0, fspi0, gspi0},
+		{"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
+	}
 
   Every map must be assigned a state name, pin controller, device and
   function. The group is not compulsory - if it is omitted the first group
@@ -578,155 +583,155 @@ some certain registers to activate a certain mux setting for a certain pin.
 
 A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
 into some register named MUX to select a certain function with a certain
-group of pins would work something like this:
-
-#include <linux/pinctrl/pinctrl.h>
-#include <linux/pinctrl/pinmux.h>
-
-struct foo_group {
-	const char *name;
-	const unsigned int *pins;
-	const unsigned num_pins;
-};
-
-static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
-static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
-static const unsigned i2c0_pins[] = { 24, 25 };
-static const unsigned mmc0_1_pins[] = { 56, 57 };
-static const unsigned mmc0_2_pins[] = { 58, 59 };
-static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
-
-static const struct foo_group foo_groups[] = {
-	{
-		.name = "spi0_0_grp",
-		.pins = spi0_0_pins,
-		.num_pins = ARRAY_SIZE(spi0_0_pins),
-	},
-	{
-		.name = "spi0_1_grp",
-		.pins = spi0_1_pins,
-		.num_pins = ARRAY_SIZE(spi0_1_pins),
-	},
+group of pins would work something like this::
+
+	#include <linux/pinctrl/pinctrl.h>
+	#include <linux/pinctrl/pinmux.h>
+
+	struct foo_group {
+		const char *name;
+		const unsigned int *pins;
+		const unsigned num_pins;
+	};
+
+	static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
+	static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
+	static const unsigned i2c0_pins[] = { 24, 25 };
+	static const unsigned mmc0_1_pins[] = { 56, 57 };
+	static const unsigned mmc0_2_pins[] = { 58, 59 };
+	static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
+
+	static const struct foo_group foo_groups[] = {
+		{
+			.name = "spi0_0_grp",
+			.pins = spi0_0_pins,
+			.num_pins = ARRAY_SIZE(spi0_0_pins),
+		},
+		{
+			.name = "spi0_1_grp",
+			.pins = spi0_1_pins,
+			.num_pins = ARRAY_SIZE(spi0_1_pins),
+		},
+		{
+			.name = "i2c0_grp",
+			.pins = i2c0_pins,
+			.num_pins = ARRAY_SIZE(i2c0_pins),
+		},
+		{
+			.name = "mmc0_1_grp",
+			.pins = mmc0_1_pins,
+			.num_pins = ARRAY_SIZE(mmc0_1_pins),
+		},
+		{
+			.name = "mmc0_2_grp",
+			.pins = mmc0_2_pins,
+			.num_pins = ARRAY_SIZE(mmc0_2_pins),
+		},
+		{
+			.name = "mmc0_3_grp",
+			.pins = mmc0_3_pins,
+			.num_pins = ARRAY_SIZE(mmc0_3_pins),
+		},
+	};
+
+
+	static int foo_get_groups_count(struct pinctrl_dev *pctldev)
 	{
-		.name = "i2c0_grp",
-		.pins = i2c0_pins,
-		.num_pins = ARRAY_SIZE(i2c0_pins),
-	},
+		return ARRAY_SIZE(foo_groups);
+	}
+
+	static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+					unsigned selector)
 	{
-		.name = "mmc0_1_grp",
-		.pins = mmc0_1_pins,
-		.num_pins = ARRAY_SIZE(mmc0_1_pins),
-	},
+		return foo_groups[selector].name;
+	}
+
+	static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+				unsigned ** const pins,
+				unsigned * const num_pins)
 	{
-		.name = "mmc0_2_grp",
-		.pins = mmc0_2_pins,
-		.num_pins = ARRAY_SIZE(mmc0_2_pins),
-	},
+		*pins = (unsigned *) foo_groups[selector].pins;
+		*num_pins = foo_groups[selector].num_pins;
+		return 0;
+	}
+
+	static struct pinctrl_ops foo_pctrl_ops = {
+		.get_groups_count = foo_get_groups_count,
+		.get_group_name = foo_get_group_name,
+		.get_group_pins = foo_get_group_pins,
+	};
+
+	struct foo_pmx_func {
+		const char *name;
+		const char * const *groups;
+		const unsigned num_groups;
+	};
+
+	static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
+	static const char * const i2c0_groups[] = { "i2c0_grp" };
+	static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
+						"mmc0_3_grp" };
+
+	static const struct foo_pmx_func foo_functions[] = {
+		{
+			.name = "spi0",
+			.groups = spi0_groups,
+			.num_groups = ARRAY_SIZE(spi0_groups),
+		},
+		{
+			.name = "i2c0",
+			.groups = i2c0_groups,
+			.num_groups = ARRAY_SIZE(i2c0_groups),
+		},
+		{
+			.name = "mmc0",
+			.groups = mmc0_groups,
+			.num_groups = ARRAY_SIZE(mmc0_groups),
+		},
+	};
+
+	static int foo_get_functions_count(struct pinctrl_dev *pctldev)
 	{
-		.name = "mmc0_3_grp",
-		.pins = mmc0_3_pins,
-		.num_pins = ARRAY_SIZE(mmc0_3_pins),
-	},
-};
-
-
-static int foo_get_groups_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_groups);
-}
-
-static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
-				       unsigned selector)
-{
-	return foo_groups[selector].name;
-}
-
-static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
-			       unsigned ** const pins,
-			       unsigned * const num_pins)
-{
-	*pins = (unsigned *) foo_groups[selector].pins;
-	*num_pins = foo_groups[selector].num_pins;
-	return 0;
-}
-
-static struct pinctrl_ops foo_pctrl_ops = {
-	.get_groups_count = foo_get_groups_count,
-	.get_group_name = foo_get_group_name,
-	.get_group_pins = foo_get_group_pins,
-};
-
-struct foo_pmx_func {
-	const char *name;
-	const char * const *groups;
-	const unsigned num_groups;
-};
-
-static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
-static const char * const i2c0_groups[] = { "i2c0_grp" };
-static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
-					"mmc0_3_grp" };
-
-static const struct foo_pmx_func foo_functions[] = {
+		return ARRAY_SIZE(foo_functions);
+	}
+
+	static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
 	{
-		.name = "spi0",
-		.groups = spi0_groups,
-		.num_groups = ARRAY_SIZE(spi0_groups),
-	},
+		return foo_functions[selector].name;
+	}
+
+	static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
+				const char * const **groups,
+				unsigned * const num_groups)
 	{
-		.name = "i2c0",
-		.groups = i2c0_groups,
-		.num_groups = ARRAY_SIZE(i2c0_groups),
-	},
+		*groups = foo_functions[selector].groups;
+		*num_groups = foo_functions[selector].num_groups;
+		return 0;
+	}
+
+	static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
+			unsigned group)
 	{
-		.name = "mmc0",
-		.groups = mmc0_groups,
-		.num_groups = ARRAY_SIZE(mmc0_groups),
-	},
-};
-
-static int foo_get_functions_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_functions);
-}
-
-static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
-{
-	return foo_functions[selector].name;
-}
-
-static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
-			  const char * const **groups,
-			  unsigned * const num_groups)
-{
-	*groups = foo_functions[selector].groups;
-	*num_groups = foo_functions[selector].num_groups;
-	return 0;
-}
-
-static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
-		unsigned group)
-{
-	u8 regbit = (1 << selector + group);
-
-	writeb((readb(MUX)|regbit), MUX)
-	return 0;
-}
-
-static struct pinmux_ops foo_pmxops = {
-	.get_functions_count = foo_get_functions_count,
-	.get_function_name = foo_get_fname,
-	.get_function_groups = foo_get_groups,
-	.set_mux = foo_set_mux,
-	.strict = true,
-};
-
-/* Pinmux operations are handled by some pin controller */
-static struct pinctrl_desc foo_desc = {
-	...
-	.pctlops = &foo_pctrl_ops,
-	.pmxops = &foo_pmxops,
-};
+		u8 regbit = (1 << selector + group);
+
+		writeb((readb(MUX)|regbit), MUX)
+		return 0;
+	}
+
+	static struct pinmux_ops foo_pmxops = {
+		.get_functions_count = foo_get_functions_count,
+		.get_function_name = foo_get_fname,
+		.get_function_groups = foo_get_groups,
+		.set_mux = foo_set_mux,
+		.strict = true,
+	};
+
+	/* Pinmux operations are handled by some pin controller */
+	static struct pinctrl_desc foo_desc = {
+		...
+		.pctlops = &foo_pctrl_ops,
+		.pmxops = &foo_pmxops,
+	};
 
 In the example activating muxing 0 and 1 at the same time setting bits
 0 and 1, uses one pin in common so they would collide.
@@ -809,9 +814,9 @@ for a device.
 
 The GPIO portions of a pin and its relation to a certain pin controller
 configuration and muxing logic can be constructed in several ways. Here
-are two examples:
+are two examples::
 
-(A)
+     (A)
                        pin config
                        logic regs
                        |               +- SPI
@@ -840,7 +845,9 @@ simultaneous access to the same pin from GPIO and pin multiplexing
 consumers on hardware of this type. The pinctrl driver should set this flag
 accordingly.
 
-(B)
+::
+
+     (B)
 
                        pin config
                        logic regs
@@ -911,52 +918,55 @@ has to be handled by the <linux/gpio.h> interface. Instead view this as
 a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
 and you find this in the documentation:
 
-  PIN_CONFIG_OUTPUT: this will configure the pin in output, use argument
+  PIN_CONFIG_OUTPUT:
+     this will configure the pin in output, use argument
      1 to indicate high level, argument 0 to indicate low level.
 
 So it is perfectly possible to push a pin into "GPIO mode" and drive the
 line low as part of the usual pin control map. So for example your UART
-driver may look like this:
+driver may look like this::
 
-#include <linux/pinctrl/consumer.h>
+	#include <linux/pinctrl/consumer.h>
 
-struct pinctrl          *pinctrl;
-struct pinctrl_state    *pins_default;
-struct pinctrl_state    *pins_sleep;
+	struct pinctrl          *pinctrl;
+	struct pinctrl_state    *pins_default;
+	struct pinctrl_state    *pins_sleep;
 
-pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
-pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
+	pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
+	pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
 
-/* Normal mode */
-retval = pinctrl_select_state(pinctrl, pins_default);
-/* Sleep mode */
-retval = pinctrl_select_state(pinctrl, pins_sleep);
+	/* Normal mode */
+	retval = pinctrl_select_state(pinctrl, pins_default);
+	/* Sleep mode */
+	retval = pinctrl_select_state(pinctrl, pins_sleep);
 
 And your machine configuration may look like this:
 --------------------------------------------------
 
-static unsigned long uart_default_mode[] = {
-    PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
-};
+::
 
-static unsigned long uart_sleep_mode[] = {
-    PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
-};
+	static unsigned long uart_default_mode[] = {
+	PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
+	};
 
-static struct pinctrl_map pinmap[] __initdata = {
-    PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
-                      "u0_group", "u0"),
-    PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
-                        "UART_TX_PIN", uart_default_mode),
-    PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
-                      "u0_group", "gpio-mode"),
-    PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
-                        "UART_TX_PIN", uart_sleep_mode),
-};
+	static unsigned long uart_sleep_mode[] = {
+	PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
+	};
 
-foo_init(void) {
-    pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
-}
+	static struct pinctrl_map pinmap[] __initdata = {
+	PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+			"u0_group", "u0"),
+	PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+				"UART_TX_PIN", uart_default_mode),
+	PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+			"u0_group", "gpio-mode"),
+	PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+				"UART_TX_PIN", uart_sleep_mode),
+	};
+
+	foo_init(void) {
+	pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
+	}
 
 Here the pins we want to control are in the "u0_group" and there is some
 function called "u0" that can be enabled on this group of pins, and then
@@ -985,7 +995,7 @@ API.
 
 
 Board/machine configuration
-==================================
+===========================
 
 Boards and machines define how a certain complete running system is put
 together, including how GPIOs and devices are muxed, how regulators are
@@ -994,33 +1004,33 @@ part of this.
 
 A pin controller configuration for a machine looks pretty much like a simple
 regulator configuration, so for the example array above we want to enable i2c
-and spi on the second function mapping:
+and spi on the second function mapping::
 
-#include <linux/pinctrl/machine.h>
+	#include <linux/pinctrl/machine.h>
 
-static const struct pinctrl_map mapping[] __initconst = {
-	{
-		.dev_name = "foo-spi.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "spi0",
-	},
-	{
-		.dev_name = "foo-i2c.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "i2c0",
-	},
-	{
-		.dev_name = "foo-mmc.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "mmc0",
-	},
-};
+	static const struct pinctrl_map mapping[] __initconst = {
+		{
+			.dev_name = "foo-spi.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "spi0",
+		},
+		{
+			.dev_name = "foo-i2c.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "i2c0",
+		},
+		{
+			.dev_name = "foo-mmc.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "mmc0",
+		},
+	};
 
 The dev_name here matches to the unique device name that can be used to look
 up the device struct (just like with clockdev or regulators). The function name
@@ -1029,76 +1039,81 @@ must match a function provided by the pinmux driver handling this pin range.
 As you can see we may have several pin controllers on the system and thus
 we need to specify which one of them contains the functions we wish to map.
 
-You register this pinmux mapping to the pinmux subsystem by simply:
+You register this pinmux mapping to the pinmux subsystem by simply::
 
        ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
 
 Since the above construct is pretty common there is a helper macro to make
 it even more compact which assumes you want to use pinctrl-foo and position
-0 for mapping, for example:
+0 for mapping, for example::
 
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"),
-};
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
+				  "pinctrl-foo", NULL, "i2c0"),
+	};
 
 The mapping table may also contain pin configuration entries. It's common for
 each pin/group to have a number of configuration entries that affect it, so
 the table entries for configuration reference an array of config parameters
-and values. An example using the convenience macros is shown below:
+and values. An example using the convenience macros is shown below::
 
-static unsigned long i2c_grp_configs[] = {
-	FOO_PIN_DRIVEN,
-	FOO_PIN_PULLUP,
-};
+	static unsigned long i2c_grp_configs[] = {
+		FOO_PIN_DRIVEN,
+		FOO_PIN_PULLUP,
+	};
 
-static unsigned long i2c_pin_configs[] = {
-	FOO_OPEN_COLLECTOR,
-	FOO_SLEW_RATE_SLOW,
-};
+	static unsigned long i2c_pin_configs[] = {
+		FOO_OPEN_COLLECTOR,
+		FOO_SLEW_RATE_SLOW,
+	};
 
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"),
-	PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs),
-	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs),
-	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs),
-};
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				  "pinctrl-foo", "i2c0", "i2c0"),
+		PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				      "pinctrl-foo", "i2c0", i2c_grp_configs),
+		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				    "pinctrl-foo", "i2c0scl", i2c_pin_configs),
+		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				    "pinctrl-foo", "i2c0sda", i2c_pin_configs),
+	};
 
 Finally, some devices expect the mapping table to contain certain specific
 named states. When running on hardware that doesn't need any pin controller
 configuration, the mapping table must still contain those named states, in
 order to explicitly indicate that the states were provided and intended to
 be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
-a named state without causing any pin controller to be programmed:
+a named state without causing any pin controller to be programmed::
 
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
-};
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
+	};
 
 
 Complex mappings
 ================
 
 As it is possible to map a function to different groups of pins an optional
-.group can be specified like this:
+.group can be specified like this::
 
-...
-{
-	.dev_name = "foo-spi.0",
-	.name = "spi0-pos-A",
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "spi0",
-	.group = "spi0_0_grp",
-},
-{
-	.dev_name = "foo-spi.0",
-	.name = "spi0-pos-B",
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "spi0",
-	.group = "spi0_1_grp",
-},
-...
+	...
+	{
+		.dev_name = "foo-spi.0",
+		.name = "spi0-pos-A",
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "spi0",
+		.group = "spi0_0_grp",
+	},
+	{
+		.dev_name = "foo-spi.0",
+		.name = "spi0-pos-B",
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "spi0",
+		.group = "spi0_1_grp",
+	},
+	...
 
 This example mapping is used to switch between two positions for spi0 at
 runtime, as described further below under the heading "Runtime pinmuxing".
@@ -1107,67 +1122,67 @@ Further it is possible for one named state to affect the muxing of several
 groups of pins, say for example in the mmc0 example above, where you can
 additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
 three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
-case), we define a mapping like this:
+case), we define a mapping like this::
 
-...
-{
-	.dev_name = "foo-mmc.0",
-	.name = "2bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "4bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "4bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_2_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_2_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_3_grp",
-},
-...
+	...
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "2bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "4bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "4bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_2_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_2_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_3_grp",
+	},
+	...
 
 The result of grabbing this mapping from the device with something like
-this (see next paragraph):
+this (see next paragraph)::
 
 	p = devm_pinctrl_get(dev);
 	s = pinctrl_lookup_state(p, "8bit");
 	ret = pinctrl_select_state(p, s);
 
-or more simply:
+or more simply::
 
 	p = devm_pinctrl_get_select(dev, "8bit");
 
@@ -1205,39 +1220,39 @@ PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
 current in sleep mode.
 
 A driver may request a certain control state to be activated, usually just the
-default state like this:
+default state like this::
 
-#include <linux/pinctrl/consumer.h>
+	#include <linux/pinctrl/consumer.h>
 
-struct foo_state {
-       struct pinctrl *p;
-       struct pinctrl_state *s;
-       ...
-};
+	struct foo_state {
+	struct pinctrl *p;
+	struct pinctrl_state *s;
+	...
+	};
 
-foo_probe()
-{
-	/* Allocate a state holder named "foo" etc */
-	struct foo_state *foo = ...;
+	foo_probe()
+	{
+		/* Allocate a state holder named "foo" etc */
+		struct foo_state *foo = ...;
 
-	foo->p = devm_pinctrl_get(&device);
-	if (IS_ERR(foo->p)) {
-		/* FIXME: clean up "foo" here */
-		return PTR_ERR(foo->p);
-	}
+		foo->p = devm_pinctrl_get(&device);
+		if (IS_ERR(foo->p)) {
+			/* FIXME: clean up "foo" here */
+			return PTR_ERR(foo->p);
+		}
 
-	foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
-	if (IS_ERR(foo->s)) {
-		/* FIXME: clean up "foo" here */
-		return PTR_ERR(s);
-	}
+		foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
+		if (IS_ERR(foo->s)) {
+			/* FIXME: clean up "foo" here */
+			return PTR_ERR(s);
+		}
 
-	ret = pinctrl_select_state(foo->s);
-	if (ret < 0) {
-		/* FIXME: clean up "foo" here */
-		return ret;
+		ret = pinctrl_select_state(foo->s);
+		if (ret < 0) {
+			/* FIXME: clean up "foo" here */
+			return ret;
+		}
 	}
-}
 
 This get/lookup/select/put sequence can just as well be handled by bus drivers
 if you don't want each and every driver to handle it and you know the
@@ -1299,16 +1314,16 @@ Drivers needing both pin control and GPIOs
 Again, it is discouraged to let drivers lookup and select pin control states
 themselves, but again sometimes this is unavoidable.
 
-So say that your driver is fetching its resources like this:
+So say that your driver is fetching its resources like this::
 
-#include <linux/pinctrl/consumer.h>
-#include <linux/gpio.h>
+	#include <linux/pinctrl/consumer.h>
+	#include <linux/gpio.h>
 
-struct pinctrl *pinctrl;
-int gpio;
+	struct pinctrl *pinctrl;
+	int gpio;
 
-pinctrl = devm_pinctrl_get_select_default(&dev);
-gpio = devm_gpio_request(&dev, 14, "foo");
+	pinctrl = devm_pinctrl_get_select_default(&dev);
+	gpio = devm_gpio_request(&dev, 14, "foo");
 
 Here we first request a certain pin state and then request GPIO 14 to be
 used. If you're using the subsystems orthogonally like this, you should
@@ -1347,21 +1362,22 @@ lookup_state() and select_state() on it immediately after the pin control
 device has been registered.
 
 This occurs for mapping table entries where the client device name is equal
-to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT.
+to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
 
-{
-	.dev_name = "pinctrl-foo",
-	.name = PINCTRL_STATE_DEFAULT,
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "power_func",
-},
+	{
+		.dev_name = "pinctrl-foo",
+		.name = PINCTRL_STATE_DEFAULT,
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "power_func",
+	},
 
 Since it may be common to request the core to hog a few always-applicable
 mux settings on the primary pin controller, there is a convenience macro for
-this:
+this::
 
-PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func")
+	PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
+				      "power_func")
 
 This gives the exact same result as the above construction.
 
@@ -1378,45 +1394,45 @@ function, but with different named in the mapping as described under
 
 This snippet first initializes a state object for both groups (in foo_probe()),
 then muxes the function in the pins defined by group A, and finally muxes it in
-on the pins defined by group B:
-
-#include <linux/pinctrl/consumer.h>
-
-struct pinctrl *p;
-struct pinctrl_state *s1, *s2;
-
-foo_probe()
-{
-	/* Setup */
-	p = devm_pinctrl_get(&device);
-	if (IS_ERR(p))
+on the pins defined by group B::
+
+	#include <linux/pinctrl/consumer.h>
+
+	struct pinctrl *p;
+	struct pinctrl_state *s1, *s2;
+
+	foo_probe()
+	{
+		/* Setup */
+		p = devm_pinctrl_get(&device);
+		if (IS_ERR(p))
+			...
+
+		s1 = pinctrl_lookup_state(foo->p, "pos-A");
+		if (IS_ERR(s1))
+			...
+
+		s2 = pinctrl_lookup_state(foo->p, "pos-B");
+		if (IS_ERR(s2))
+			...
+	}
+
+	foo_switch()
+	{
+		/* Enable on position A */
+		ret = pinctrl_select_state(s1);
+		if (ret < 0)
 		...
 
-	s1 = pinctrl_lookup_state(foo->p, "pos-A");
-	if (IS_ERR(s1))
 		...
 
-	s2 = pinctrl_lookup_state(foo->p, "pos-B");
-	if (IS_ERR(s2))
+		/* Enable on position B */
+		ret = pinctrl_select_state(s2);
+		if (ret < 0)
 		...
-}
-
-foo_switch()
-{
-	/* Enable on position A */
-	ret = pinctrl_select_state(s1);
-	if (ret < 0)
-	    ...
 
-	...
-
-	/* Enable on position B */
-	ret = pinctrl_select_state(s2);
-	if (ret < 0)
-	    ...
-
-	...
-}
+		...
+	}
 
 The above has to be done from process context. The reservation of the pins
 will be done when the state is activated, so in effect one specific pin
-- 
2.9.4

[PATCH 02/29] pnp.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Use a markup for document title;
- use :Author: and :Last updated: for authorship;
- adjust whitespaces where needed;
- mark literal blocks;
- fix a few subtitle markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/pnp.txt | 343 ++++++++++++++++++++++++++++----------------------
 1 file changed, 192 insertions(+), 151 deletions(-)

diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt
index 763e4659bf18..bab2d10631f0 100644
--- a/Documentation/pnp.txt
+++ b/Documentation/pnp.txt
@@ -1,98 +1,118 @@
+=================================
 Linux Plug and Play Documentation
-by Adam Belay <ambx1@neo.rr.com>
-last updated: Oct. 16, 2002
----------------------------------------------------------------------------------------
+=================================
 
+:Author: Adam Belay <ambx1@neo.rr.com>
+:Last updated: Oct. 16, 2002
 
 
 Overview
 --------
-	Plug and Play provides a means of detecting and setting resources for legacy or
+
+Plug and Play provides a means of detecting and setting resources for legacy or
 otherwise unconfigurable devices.  The Linux Plug and Play Layer provides these 
 services to compatible drivers.
 
 
-
 The User Interface
 ------------------
-	The Linux Plug and Play user interface provides a means to activate PnP devices
+
+The Linux Plug and Play user interface provides a means to activate PnP devices
 for legacy and user level drivers that do not support Linux Plug and Play.  The 
 user interface is integrated into sysfs.
 
 In addition to the standard sysfs file the following are created in each
 device's directory:
-id - displays a list of support EISA IDs
-options - displays possible resource configurations
-resources - displays currently allocated resources and allows resource changes
+- id - displays a list of support EISA IDs
+- options - displays possible resource configurations
+- resources - displays currently allocated resources and allows resource changes
 
--activating a device
+activating a device
+^^^^^^^^^^^^^^^^^^^
 
-#echo "auto" > resources
+::
+
+	# echo "auto" > resources
 
 this will invoke the automatic resource config system to activate the device
 
--manually activating a device
+manually activating a device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-#echo "manual <depnum> <mode>" > resources
-<depnum> - the configuration number
-<mode> - static or dynamic
-		static = for next boot
-		dynamic = now
+::
 
--disabling a device
+	# echo "manual <depnum> <mode>" > resources
 
-#echo "disable" > resources
+	<depnum> - the configuration number
+	<mode> - static or dynamic
+		 static = for next boot
+		 dynamic = now
+
+disabling a device
+^^^^^^^^^^^^^^^^^^
+
+::
+
+	# echo "disable" > resources
 
 
 EXAMPLE:
 
 Suppose you need to activate the floppy disk controller.
-1.) change to the proper directory, in my case it is 
-/driver/bus/pnp/devices/00:0f
-# cd /driver/bus/pnp/devices/00:0f
-# cat name
-PC standard floppy disk controller
-
-2.) check if the device is already active
-# cat resources
-DISABLED
-
-- Notice the string "DISABLED".  This means the device is not active.
-
-3.) check the device's possible configurations (optional)
-# cat options
-Dependent: 01 - Priority acceptable
-    port 0x3f0-0x3f0, align 0x7, size 0x6, 16-bit address decoding
-    port 0x3f7-0x3f7, align 0x0, size 0x1, 16-bit address decoding
-    irq 6
-    dma 2 8-bit compatible
-Dependent: 02 - Priority acceptable
-    port 0x370-0x370, align 0x7, size 0x6, 16-bit address decoding
-    port 0x377-0x377, align 0x0, size 0x1, 16-bit address decoding
-    irq 6
-    dma 2 8-bit compatible
-
-4.) now activate the device
-# echo "auto" > resources
-
-5.) finally check if the device is active
-# cat resources
-io 0x3f0-0x3f5
-io 0x3f7-0x3f7
-irq 6
-dma 2
-
-also there are a series of kernel parameters:
-pnp_reserve_irq=irq1[,irq2] ....
-pnp_reserve_dma=dma1[,dma2] ....
-pnp_reserve_io=io1,size1[,io2,size2] ....
-pnp_reserve_mem=mem1,size1[,mem2,size2] ....
+
+1. change to the proper directory, in my case it is
+   /driver/bus/pnp/devices/00:0f::
+
+	# cd /driver/bus/pnp/devices/00:0f
+	# cat name
+	PC standard floppy disk controller
+
+2. check if the device is already active::
+
+	# cat resources
+	DISABLED
+
+  - Notice the string "DISABLED".  This means the device is not active.
+
+3. check the device's possible configurations (optional)::
+
+	# cat options
+	Dependent: 01 - Priority acceptable
+	    port 0x3f0-0x3f0, align 0x7, size 0x6, 16-bit address decoding
+	    port 0x3f7-0x3f7, align 0x0, size 0x1, 16-bit address decoding
+	    irq 6
+	    dma 2 8-bit compatible
+	Dependent: 02 - Priority acceptable
+	    port 0x370-0x370, align 0x7, size 0x6, 16-bit address decoding
+	    port 0x377-0x377, align 0x0, size 0x1, 16-bit address decoding
+	    irq 6
+	    dma 2 8-bit compatible
+
+4. now activate the device::
+
+	# echo "auto" > resources
+
+5. finally check if the device is active::
+
+	# cat resources
+	io 0x3f0-0x3f5
+	io 0x3f7-0x3f7
+	irq 6
+	dma 2
+
+also there are a series of kernel parameters::
+
+	pnp_reserve_irq=irq1[,irq2] ....
+	pnp_reserve_dma=dma1[,dma2] ....
+	pnp_reserve_io=io1,size1[,io2,size2] ....
+	pnp_reserve_mem=mem1,size1[,mem2,size2] ....
 
 
 
 The Unified Plug and Play Layer
 -------------------------------
-	All Plug and Play drivers, protocols, and services meet at a central location 
+
+All Plug and Play drivers, protocols, and services meet at a central location
 called the Plug and Play Layer.  This layer is responsible for the exchange of 
 information between PnP drivers and PnP protocols.  Thus it automatically 
 forwards commands to the proper protocol.  This makes writing PnP drivers 
@@ -101,64 +121,73 @@ significantly easier.
 The following functions are available from the Plug and Play Layer:
 
 pnp_get_protocol
-- increments the number of uses by one
+  increments the number of uses by one
 
 pnp_put_protocol
-- deincrements the number of uses by one
+  deincrements the number of uses by one
 
 pnp_register_protocol
-- use this to register a new PnP protocol
+  use this to register a new PnP protocol
 
 pnp_unregister_protocol
-- use this function to remove a PnP protocol from the Plug and Play Layer
+  use this function to remove a PnP protocol from the Plug and Play Layer
 
 pnp_register_driver
-- adds a PnP driver to the Plug and Play Layer
-- this includes driver model integration
-- returns zero for success or a negative error number for failure; count
+  adds a PnP driver to the Plug and Play Layer
+
+  this includes driver model integration
+  returns zero for success or a negative error number for failure; count
   calls to the .add() method if you need to know how many devices bind to
   the driver
 
 pnp_unregister_driver
-- removes a PnP driver from the Plug and Play Layer
+  removes a PnP driver from the Plug and Play Layer
 
 
 
 Plug and Play Protocols
 -----------------------
-	This section contains information for PnP protocol developers.
+
+This section contains information for PnP protocol developers.
 
 The following Protocols are currently available in the computing world:
-- PNPBIOS: used for system devices such as serial and parallel ports.
-- ISAPNP: provides PnP support for the ISA bus
-- ACPI: among its many uses, ACPI provides information about system level 
-devices.
+
+- PNPBIOS:
+    used for system devices such as serial and parallel ports.
+- ISAPNP:
+    provides PnP support for the ISA bus
+- ACPI:
+    among its many uses, ACPI provides information about system level
+    devices.
+
 It is meant to replace the PNPBIOS.  It is not currently supported by Linux
 Plug and Play but it is planned to be in the near future.
 
 
 Requirements for a Linux PnP protocol:
-1.) the protocol must use EISA IDs
-2.) the protocol must inform the PnP Layer of a device's current configuration
+1. the protocol must use EISA IDs
+2. the protocol must inform the PnP Layer of a device's current configuration
+
 - the ability to set resources is optional but preferred.
 
 The following are PnP protocol related functions:
 
 pnp_add_device
-- use this function to add a PnP device to the PnP layer
-- only call this function when all wanted values are set in the pnp_dev 
-structure
+  use this function to add a PnP device to the PnP layer
+
+  only call this function when all wanted values are set in the pnp_dev
+  structure
 
 pnp_init_device
-- call this to initialize the PnP structure
+  call this to initialize the PnP structure
 
 pnp_remove_device
-- call this to remove a device from the Plug and Play Layer.
-- it will fail if the device is still in use.
-- automatically will free mem used by the device and related structures
+  call this to remove a device from the Plug and Play Layer.
+  it will fail if the device is still in use.
+  automatically will free mem used by the device and related structures
 
 pnp_add_id
-- adds an EISA ID to the list of supported IDs for the specified device
+  adds an EISA ID to the list of supported IDs for the specified device
 
 For more information consult the source of a protocol such as
 /drivers/pnp/pnpbios/core.c.
@@ -167,85 +196,97 @@ For more information consult the source of a protocol such as
 
 Linux Plug and Play Drivers
 ---------------------------
-	This section contains information for Linux PnP driver developers.
+
+This section contains information for Linux PnP driver developers.
 
 The New Way
-...........
-1.) first make a list of supported EISA IDS
-ex:
-static const struct pnp_id pnp_dev_table[] = {
-	/* Standard LPT Printer Port */
-	{.id = "PNP0400", .driver_data = 0},
-	/* ECP Printer Port */
-	{.id = "PNP0401", .driver_data = 0},
-	{.id = ""}
-};
-
-Please note that the character 'X' can be used as a wild card in the function
-portion (last four characters).
-ex:
+^^^^^^^^^^^
+
+1. first make a list of supported EISA IDS
+
+   ex::
+
+	static const struct pnp_id pnp_dev_table[] = {
+		/* Standard LPT Printer Port */
+		{.id = "PNP0400", .driver_data = 0},
+		/* ECP Printer Port */
+		{.id = "PNP0401", .driver_data = 0},
+		{.id = ""}
+	};
+
+   Please note that the character 'X' can be used as a wild card in the function
+   portion (last four characters).
+
+   ex::
+
 	/* Unknown PnP modems */
 	{	"PNPCXXX",		UNKNOWN_DEV	},
 
-Supported PnP card IDs can optionally be defined.
-ex:
-static const struct pnp_id pnp_card_table[] = {
-	{	"ANYDEVS",		0	},
-	{	"",			0	}
-};
-
-2.) Optionally define probe and remove functions.  It may make sense not to 
-define these functions if the driver already has a reliable method of detecting
-the resources, such as the parport_pc driver.
-ex:
-static int
-serial_pnp_probe(struct pnp_dev * dev, const struct pnp_id *card_id, const 
-                 struct pnp_id *dev_id)
-{
-. . .
-
-ex:
-static void serial_pnp_remove(struct pnp_dev * dev)
-{
-. . .
-
-consult /drivers/serial/8250_pnp.c for more information.
-
-3.) create a driver structure
-ex:
-
-static struct pnp_driver serial_pnp_driver = {
-	.name		= "serial",
-	.card_id_table	= pnp_card_table,
-	.id_table	= pnp_dev_table,
-	.probe		= serial_pnp_probe,
-	.remove		= serial_pnp_remove,
-};
-
-* name and id_table cannot be NULL.
-
-4.) register the driver
-ex:
-
-static int __init serial8250_pnp_init(void)
-{
-	return pnp_register_driver(&serial_pnp_driver);
-}
+   Supported PnP card IDs can optionally be defined.
+   ex::
+
+	static const struct pnp_id pnp_card_table[] = {
+		{	"ANYDEVS",		0	},
+		{	"",			0	}
+	};
+
+2. Optionally define probe and remove functions.  It may make sense not to
+   define these functions if the driver already has a reliable method of detecting
+   the resources, such as the parport_pc driver.
+
+   ex::
+
+	static int
+	serial_pnp_probe(struct pnp_dev * dev, const struct pnp_id *card_id, const
+			struct pnp_id *dev_id)
+	{
+	. . .
+
+   ex::
+
+	static void serial_pnp_remove(struct pnp_dev * dev)
+	{
+	. . .
+
+   consult /drivers/serial/8250_pnp.c for more information.
+
+3. create a driver structure
+
+   ex::
+
+	static struct pnp_driver serial_pnp_driver = {
+		.name		= "serial",
+		.card_id_table	= pnp_card_table,
+		.id_table	= pnp_dev_table,
+		.probe		= serial_pnp_probe,
+		.remove		= serial_pnp_remove,
+	};
+
+   * name and id_table cannot be NULL.
+
+4. register the driver
+
+   ex::
+
+	static int __init serial8250_pnp_init(void)
+	{
+		return pnp_register_driver(&serial_pnp_driver);
+	}
 
 The Old Way
-...........
+^^^^^^^^^^^
 
 A series of compatibility functions have been created to make it easy to convert
 ISAPNP drivers.  They should serve as a temporary solution only.
 
-They are as follows:
+They are as follows::
 
-struct pnp_card *pnp_find_card(unsigned short vendor,
-				 unsigned short device,
-				 struct pnp_card *from)
+	struct pnp_card *pnp_find_card(unsigned short vendor,
+				       unsigned short device,
+				       struct pnp_card *from)
 
-struct pnp_dev *pnp_find_dev(struct pnp_card *card,
-				unsigned short vendor,
-				unsigned short function,
-				struct pnp_dev *from)
+	struct pnp_dev *pnp_find_dev(struct pnp_card *card,
+				     unsigned short vendor,
+				     unsigned short function,
+				     struct pnp_dev *from)
 
-- 
2.9.4

[PATCH 03/29] preempt-locking.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark titles;
- mark literal blocks;
- adjust identation where needed;
- use :Author: for authorship.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/preempt-locking.txt | 40 ++++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.txt
index e89ce6624af2..c945062be66c 100644
--- a/Documentation/preempt-locking.txt
+++ b/Documentation/preempt-locking.txt
@@ -1,10 +1,13 @@
-		  Proper Locking Under a Preemptible Kernel:
-		       Keeping Kernel Code Preempt-Safe
-			 Robert Love <rml@tech9.net>
-			  Last Updated: 28 Aug 2002
+===========================================================================
+Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe
+===========================================================================
 
+:Author: Robert Love <rml@tech9.net>
+:Last Updated: 28 Aug 2002
 
-INTRODUCTION
+
+Introduction
+============
 
 
 A preemptible kernel creates new locking issues.  The issues are the same as
@@ -17,9 +20,10 @@ requires protecting these situations.
  
 
 RULE #1: Per-CPU data structures need explicit protection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-Two similar problems arise. An example code snippet:
+Two similar problems arise. An example code snippet::
 
 	struct this_needs_locking tux[NR_CPUS];
 	tux[smp_processor_id()] = some_value;
@@ -35,6 +39,7 @@ You can also use put_cpu() and get_cpu(), which will disable preemption.
 
 
 RULE #2: CPU state must be protected.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 Under preemption, the state of the CPU must be protected.  This is arch-
@@ -52,6 +57,7 @@ However, fpu__restore() must be called with preemption disabled.
 
 
 RULE #3: Lock acquire and release must be performed by same task
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 A lock acquired in one task must be released by the same task.  This
@@ -61,17 +67,20 @@ like this, acquire and release the task in the same code path and
 have the caller wait on an event by the other task.
 
 
-SOLUTION
+Solution
+========
 
 
 Data protection under preemption is achieved by disabling preemption for the
 duration of the critical region.
 
-preempt_enable()		decrement the preempt counter
-preempt_disable()		increment the preempt counter
-preempt_enable_no_resched()	decrement, but do not immediately preempt
-preempt_check_resched()		if needed, reschedule
-preempt_count()			return the preempt counter
+::
+
+  preempt_enable()		decrement the preempt counter
+  preempt_disable()		increment the preempt counter
+  preempt_enable_no_resched()	decrement, but do not immediately preempt
+  preempt_check_resched()	if needed, reschedule
+  preempt_count()		return the preempt counter
 
 The functions are nestable.  In other words, you can call preempt_disable
 n-times in a code path, and preemption will not be reenabled until the n-th
@@ -89,7 +98,7 @@ So use this implicit preemption-disabling property only if you know that the
 affected codepath does not do any of this. Best policy is to use this only for
 small, atomic code that you wrote and which calls no complex functions.
 
-Example:
+Example::
 
 	cpucache_t *cc; /* this is per-CPU */
 	preempt_disable();
@@ -102,7 +111,7 @@ Example:
 	return 0;
 
 Notice how the preemption statements must encompass every reference of the
-critical variables.  Another example:
+critical variables.  Another example::
 
 	int buf[NR_CPUS];
 	set_cpu_val(buf);
@@ -114,7 +123,8 @@ This code is not preempt-safe, but see how easily we can fix it by simply
 moving the spin_lock up two lines.
 
 
-PREVENTING PREEMPTION USING INTERRUPT DISABLING
+Preventing preemption using interrupt disabling
+===============================================
 
 
 It is possible to prevent a preemption event using local_irq_disable and
-- 
2.9.4

[PATCH 04/29] printk-formats.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- add a title for the document;
- add markups for section titles;
- move authorship to the beginning and use :Author:;
- use right markup for tables;
- mark literals and literal blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/printk-formats.txt | 416 +++++++++++++++++++++++----------------
 1 file changed, 243 insertions(+), 173 deletions(-)

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..13cb8491731b 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.txt
@@ -1,139 +1,180 @@
-If variable is of Type,		use printk format specifier:
----------------------------------------------------------
-		int			%d or %x
-		unsigned int		%u or %x
-		long			%ld or %lx
-		unsigned long		%lu or %lx
-		long long		%lld or %llx
-		unsigned long long	%llu or %llx
-		size_t			%zu or %zx
-		ssize_t			%zd or %zx
-		s32			%d or %x
-		u32			%u or %x
-		s64			%lld or %llx
-		u64			%llu or %llx
+How to get printk format specifiers right
+=========================================
 
-If <type> is dependent on a config option for its size (e.g., sector_t,
-blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
-format specifier of its largest possible type and explicitly cast to it.
-Example:
+:Author: Randy Dunlap <rdunlap@infradead.org>
+:Author: Andrew Murray <amurray@mpc-data.co.uk>
+
+
+Integer types
+=============
+
+======================= ===========================
+If variable is of Type	use printk format specifier
+======================= ===========================
+``int``			``%d or %x``
+``unsigned int``	``%u or %x``
+``long``		``%ld or %lx``
+``unsigned long``	``%lu or %lx``
+``long long``		``%lld or %llx``
+``unsigned long long``	``%llu or %llx``
+``size_t``		``%zu or %zx``
+``ssize_t``		``%zd or %zx``
+``s32``			``%d or %x``
+``u32``			``%u or %x``
+``s64``			``%lld or %llx``
+``u64``			``%llu or %llx``
+======================= ===========================
+
+If <type> is dependent on a config option for its size (e.g., ``sector_t``,
+``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
+use a format specifier of its largest possible type and explicitly cast to it.
+
+Example::
 
 	printk("test: sector number/total blocks: %llu/%llu\n",
 		(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: sizeof() result is of type size_t.
+Reminder: ``sizeof()`` result is of type ``size_t``.
 
-The kernel's printf does not support %n. For obvious reasons, floating
-point formats (%e, %f, %g, %a) are also not recognized. Use of any
+The kernel's printf does not support ``%n``. For obvious reasons, floating
+point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
 unsupported specifier or length qualifier results in a WARN and early
 return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
 
-Symbols/Function Pointers:
+Symbols/Function Pointers
+=========================
 
-	%pF	versatile_init+0x0/0x110
-	%pf	versatile_init
-	%pS	versatile_init+0x0/0x110
-	%pSR	versatile_init+0x9/0x110
-		(with __builtin_extract_return_addr() translation)
-	%ps	versatile_init
-	%pB	prev_fn_of_versatile_init+0x88/0x88
+======================= ======================================================
+If variable is of Type	use printk format specifier
+======================= ======================================================
+``%pF``			``versatile_init+0x0/0x110``
+``%pf``			``versatile_init``
+``%pS``			``versatile_init+0x0/0x110``
+``%pSR``		``versatile_init+0x9/0x110``
+			``(with __builtin_extract_return_addr() translation)``
+``%ps``			``versatile_init``
+``%pB``			``prev_fn_of_versatile_init+0x88/0x88``
+======================= ======================================================
 
-	For printing symbols and function pointers. The 'S' and 's' specifiers
-	result in the symbol name with ('S') or without ('s') offsets. Where
-	this is used on a kernel without KALLSYMS - the symbol address is
-	printed instead.
+For printing symbols and function pointers. The ``S`` and ``s`` specifiers
+result in the symbol name with (``S``) or without (``s``) offsets. Where
+this is used on a kernel without KALLSYMS - the symbol address is
+printed instead.
 
-	The 'B' specifier results in the symbol name with offsets and should be
-	used when printing stack backtraces. The specifier takes into
-	consideration the effect of compiler optimisations which may occur
-	when tail-call's are used and marked with the noreturn GCC attribute.
+The ``B`` specifier results in the symbol name with offsets and should be
+used when printing stack backtraces. The specifier takes into
+consideration the effect of compiler optimisations which may occur
+when tail-call``s are used and marked with the noreturn GCC attribute.
 
-	On ia64, ppc64 and parisc64 architectures function pointers are
-	actually function descriptors which must first be resolved. The 'F' and
-	'f' specifiers perform this resolution and then provide the same
-	functionality as the 'S' and 's' specifiers.
+On ia64, ppc64 and parisc64 architectures function pointers are
+actually function descriptors which must first be resolved. The ``F`` and
+``f`` specifiers perform this resolution and then provide the same
+functionality as the ``S`` and ``s`` specifiers.
 
-Kernel Pointers:
+Kernel Pointers
+===============
+
+::
 
 	%pK	0x01234567 or 0x0123456789abcdef
 
-	For printing kernel pointers which should be hidden from unprivileged
-	users. The behaviour of %pK depends on the kptr_restrict sysctl - see
-	Documentation/sysctl/kernel.txt for more details.
+For printing kernel pointers which should be hidden from unprivileged
+users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see
+Documentation/sysctl/kernel.txt for more details.
 
-Struct Resources:
+Struct Resources
+================
+
+::
 
 	%pr	[mem 0x60000000-0x6fffffff flags 0x2200] or
 		[mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
 	%pR	[mem 0x60000000-0x6fffffff pref] or
 		[mem 0x0000000060000000-0x000000006fffffff pref]
 
-	For printing struct resources. The 'R' and 'r' specifiers result in a
-	printed resource with ('R') or without ('r') a decoded flags member.
-	Passed by reference.
+For printing struct resources. The ``R`` and ``r`` specifiers result in a
+printed resource with (``R``) or without (``r``) a decoded flags member.
+Passed by reference.
 
-Physical addresses types phys_addr_t:
+Physical addresses types ``phys_addr_t``
+========================================
+
+::
 
 	%pa[p]	0x01234567 or 0x0123456789abcdef
 
-	For printing a phys_addr_t type (and its derivatives, such as
-	resource_size_t) which can vary based on build options, regardless of
-	the width of the CPU data path. Passed by reference.
+For printing a ``phys_addr_t`` type (and its derivatives, such as
+``resource_size_t``) which can vary based on build options, regardless of
+the width of the CPU data path. Passed by reference.
 
-DMA addresses types dma_addr_t:
+DMA addresses types ``dma_addr_t``
+==================================
+
+::
 
 	%pad	0x01234567 or 0x0123456789abcdef
 
-	For printing a dma_addr_t type which can vary based on build options,
-	regardless of the width of the CPU data path. Passed by reference.
+For printing a ``dma_addr_t`` type which can vary based on build options,
+regardless of the width of the CPU data path. Passed by reference.
 
-Raw buffer as an escaped string:
+Raw buffer as an escaped string
+===============================
+
+::
 
 	%*pE[achnops]
 
-	For printing raw buffer as an escaped string. For the following buffer
+For printing raw buffer as an escaped string. For the following buffer::
 
 		1b 62 20 5c 43 07 22 90 0d 5d
 
-	few examples show how the conversion would be done (the result string
-	without surrounding quotes):
+few examples show how the conversion would be done (the result string
+without surrounding quotes)::
 
 		%*pE		"\eb \C\a"\220\r]"
 		%*pEhp		"\x1bb \C\x07"\x90\x0d]"
 		%*pEa		"\e\142\040\\\103\a\042\220\r\135"
 
-	The conversion rules are applied according to an optional combination
-	of flags (see string_escape_mem() kernel documentation for the
-	details):
-		a - ESCAPE_ANY
-		c - ESCAPE_SPECIAL
-		h - ESCAPE_HEX
-		n - ESCAPE_NULL
-		o - ESCAPE_OCTAL
-		p - ESCAPE_NP
-		s - ESCAPE_SPACE
-	By default ESCAPE_ANY_NP is used.
+The conversion rules are applied according to an optional combination
+of flags (see :c:func:`string_escape_mem` kernel documentation for the
+details):
 
-	ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
-	printing SSIDs.
+	- ``a`` - ESCAPE_ANY
+	- ``c`` - ESCAPE_SPECIAL
+	- ``h`` - ESCAPE_HEX
+	- ``n`` - ESCAPE_NULL
+	- ``o`` - ESCAPE_OCTAL
+	- ``p`` - ESCAPE_NP
+	- ``s`` - ESCAPE_SPACE
 
-	If field width is omitted the 1 byte only will be escaped.
+By default ESCAPE_ANY_NP is used.
 
-Raw buffer as a hex string:
+ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
+printing SSIDs.
+
+If field width is omitted the 1 byte only will be escaped.
+
+Raw buffer as a hex string
+==========================
+
+::
 
 	%*ph	00 01 02  ...  3f
 	%*phC	00:01:02: ... :3f
 	%*phD	00-01-02- ... -3f
 	%*phN	000102 ... 3f
 
-	For printing a small buffers (up to 64 bytes long) as a hex string with
-	certain separator. For the larger buffers consider to use
-	print_hex_dump().
+For printing a small buffers (up to 64 bytes long) as a hex string with
+certain separator. For the larger buffers consider to use
+:c:func:`print_hex_dump`.
 
-MAC/FDDI addresses:
+MAC/FDDI addresses
+==================
+
+::
 
 	%pM	00:01:02:03:04:05
 	%pMR	05:04:03:02:01:00
@@ -141,53 +182,62 @@ MAC/FDDI addresses:
 	%pm	000102030405
 	%pmR	050403020100
 
-	For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm'
-	specifiers result in a printed address with ('M') or without ('m') byte
-	separators. The default byte separator is the colon (':').
+For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
+specifiers result in a printed address with (``M``) or without (``m``) byte
+separators. The default byte separator is the colon (``:``).
 
-	Where FDDI addresses are concerned the 'F' specifier can be used after
-	the 'M' specifier to use dash ('-') separators instead of the default
-	separator.
+Where FDDI addresses are concerned the ``F`` specifier can be used after
+the ``M`` specifier to use dash (``-``) separators instead of the default
+separator.
 
-	For Bluetooth addresses the 'R' specifier shall be used after the 'M'
-	specifier to use reversed byte order suitable for visual interpretation
-	of Bluetooth addresses which are in the little endian order.
+For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
+specifier to use reversed byte order suitable for visual interpretation
+of Bluetooth addresses which are in the little endian order.
 
-	Passed by reference.
+Passed by reference.
 
-IPv4 addresses:
+IPv4 addresses
+==============
+
+::
 
 	%pI4	1.2.3.4
 	%pi4	001.002.003.004
 	%p[Ii]4[hnbl]
 
-	For printing IPv4 dot-separated decimal addresses. The 'I4' and 'i4'
-	specifiers result in a printed address with ('i4') or without ('I4')
-	leading zeros.
+For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
+specifiers result in a printed address with (``i4``) or without (``I4``)
+leading zeros.
 
-	The additional 'h', 'n', 'b', and 'l' specifiers are used to specify
-	host, network, big or little endian order addresses respectively. Where
-	no specifier is provided the default network/big endian order is used.
+The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
+host, network, big or little endian order addresses respectively. Where
+no specifier is provided the default network/big endian order is used.
 
-	Passed by reference.
+Passed by reference.
 
-IPv6 addresses:
+IPv6 addresses
+==============
+
+::
 
 	%pI6	0001:0002:0003:0004:0005:0006:0007:0008
 	%pi6	00010002000300040005000600070008
 	%pI6c	1:2:3:4:5:6:7:8
 
-	For printing IPv6 network-order 16-bit hex addresses. The 'I6' and 'i6'
-	specifiers result in a printed address with ('I6') or without ('i6')
-	colon-separators. Leading zeros are always used.
+For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
+specifiers result in a printed address with (``I6``) or without (``i6``)
+colon-separators. Leading zeros are always used.
 
-	The additional 'c' specifier can be used with the 'I' specifier to
-	print a compressed IPv6 address as described by
-	http://tools.ietf.org/html/rfc5952
+The additional ``c`` specifier can be used with the ``I`` specifier to
+print a compressed IPv6 address as described by
+http://tools.ietf.org/html/rfc5952
 
-	Passed by reference.
+Passed by reference.
 
-IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
+IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
+=========================================================
+
+::
 
 	%pIS	1.2.3.4		or 0001:0002:0003:0004:0005:0006:0007:0008
 	%piS	001.002.003.004	or 00010002000300040005000600070008
@@ -195,141 +245,161 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
 	%pISpc	1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345
 	%p[Ii]S[pfschnbl]
 
-	For printing an IP address without the need to distinguish whether it's
-	of type AF_INET or AF_INET6, a pointer to a valid 'struct sockaddr',
-	specified through 'IS' or 'iS', can be passed to this format specifier.
+For printing an IP address without the need to distinguish whether it``s
+of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``,
+specified through ``IS`` or ``iS``, can be passed to this format specifier.
 
-	The additional 'p', 'f', and 's' specifiers are used to specify port
-	(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ':' prefix,
-	flowinfo a '/' and scope a '%', each followed by the actual value.
+The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
+(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
+flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
 
-	In case of an IPv6 address the compressed IPv6 address as described by
-	http://tools.ietf.org/html/rfc5952 is being used if the additional
-	specifier 'c' is given. The IPv6 address is surrounded by '[', ']' in
-	case of additional specifiers 'p', 'f' or 's' as suggested by
-	https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
+In case of an IPv6 address the compressed IPv6 address as described by
+http://tools.ietf.org/html/rfc5952 is being used if the additional
+specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
+case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
+https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
 
-	In case of IPv4 addresses, the additional 'h', 'n', 'b', and 'l'
-	specifiers can be used as well and are ignored in case of an IPv6
-	address.
+In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
+specifiers can be used as well and are ignored in case of an IPv6
+address.
 
-	Passed by reference.
+Passed by reference.
 
-	Further examples:
+Further examples::
 
 	%pISfc		1.2.3.4		or [1:2:3:4:5:6:7:8]/123456789
 	%pISsc		1.2.3.4		or [1:2:3:4:5:6:7:8]%1234567890
 	%pISpfc		1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345/123456789
 
-UUID/GUID addresses:
+UUID/GUID addresses
+===================
+
+::
 
 	%pUb	00010203-0405-0607-0809-0a0b0c0d0e0f
 	%pUB	00010203-0405-0607-0809-0A0B0C0D0E0F
 	%pUl	03020100-0504-0706-0809-0a0b0c0e0e0f
 	%pUL	03020100-0504-0706-0809-0A0B0C0E0E0F
 
-	For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
-	'b' and 'B' specifiers are used to specify a little endian order in
-	lower ('l') or upper case ('L') hex characters - and big endian order
-	in lower ('b') or upper case ('B') hex characters.
+For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
+'b' and 'B' specifiers are used to specify a little endian order in
+lower ('l') or upper case ('L') hex characters - and big endian order
+in lower ('b') or upper case ('B') hex characters.
 
-	Where no additional specifiers are used the default big endian
-	order with lower case hex characters will be printed.
+Where no additional specifiers are used the default big endian
+order with lower case hex characters will be printed.
 
-	Passed by reference.
+Passed by reference.
 
-dentry names:
+dentry names
+============
+
+::
 
 	%pd{,2,3,4}
 	%pD{,2,3,4}
 
-	For printing dentry name; if we race with d_move(), the name might be
-	a mix of old and new ones, but it won't oops.  %pd dentry is a safer
-	equivalent of %s dentry->d_name.name we used to use, %pd<n> prints
-	n last components.  %pD does the same thing for struct file.
+For printing dentry name; if we race with :c:func:`d_move`, the name might be
+a mix of old and new ones, but it won't oops.  ``%pd`` dentry is a safer
+equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints
+``n`` last components.  ``%pD`` does the same thing for struct file.
 
-	Passed by reference.
+Passed by reference.
 
-block_device names:
+block_device names
+==================
+
+::
 
 	%pg	sda, sda1 or loop0p1
 
-	For printing name of block_device pointers.
+For printing name of block_device pointers.
 
-struct va_format:
+struct va_format
+================
+
+::
 
 	%pV
 
-	For printing struct va_format structures. These contain a format string
-	and va_list as follows:
+For printing struct va_format structures. These contain a format string
+and va_list as follows::
 
 	struct va_format {
 		const char *fmt;
 		va_list *va;
 	};
 
-	Implements a "recursive vsnprintf".
+Implements a "recursive vsnprintf".
 
-	Do not use this feature without some mechanism to verify the
-	correctness of the format string and va_list arguments.
+Do not use this feature without some mechanism to verify the
+correctness of the format string and va_list arguments.
 
-	Passed by reference.
+Passed by reference.
 
-struct clk:
+struct clk
+==========
+
+::
 
 	%pC	pll1
 	%pCn	pll1
 	%pCr	1560000000
 
-	For printing struct clk structures. '%pC' and '%pCn' print the name
-	(Common Clock Framework) or address (legacy clock framework) of the
-	structure; '%pCr' prints the current clock rate.
+For printing struct clk structures. ``%pC`` and ``%pCn`` print the name
+(Common Clock Framework) or address (legacy clock framework) of the
+structure; ``%pCr`` prints the current clock rate.
 
-	Passed by reference.
+Passed by reference.
 
-bitmap and its derivatives such as cpumask and nodemask:
+bitmap and its derivatives such as cpumask and nodemask
+=======================================================
+
+::
 
 	%*pb	0779
 	%*pbl	0,3-6,8-10
 
-	For printing bitmap and its derivatives such as cpumask and nodemask,
-	%*pb output the bitmap with field width as the number of bits and %*pbl
-	output the bitmap as range list with field width as the number of bits.
+For printing bitmap and its derivatives such as cpumask and nodemask,
+``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl``
+output the bitmap as range list with field width as the number of bits.
 
-	Passed by reference.
+Passed by reference.
 
-Flags bitfields such as page flags, gfp_flags:
+Flags bitfields such as page flags, gfp_flags
+=============================================
+
+::
 
 	%pGp	referenced|uptodate|lru|active|private
 	%pGg	GFP_USER|GFP_DMA32|GFP_NOWARN
 	%pGv	read|exec|mayread|maywrite|mayexec|denywrite
 
-	For printing flags bitfields as a collection of symbolic constants that
-	would construct the value. The type of flags is given by the third
-	character. Currently supported are [p]age flags, [v]ma_flags (both
-	expect unsigned long *) and [g]fp_flags (expects gfp_t *). The flag
-	names and print order depends on the particular	type.
+For printing flags bitfields as a collection of symbolic constants that
+would construct the value. The type of flags is given by the third
+character. Currently supported are [p]age flags, [v]ma_flags (both
+expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
+names and print order depends on the particular	type.
 
-	Note that this format should not be used directly in TP_printk() part
-	of a tracepoint. Instead, use the show_*_flags() functions from
-	<trace/events/mmflags.h>.
+Note that this format should not be used directly in :c:func:`TP_printk()` part
+of a tracepoint. Instead, use the ``show_*_flags()`` functions from
+<trace/events/mmflags.h>.
 
-	Passed by reference.
+Passed by reference.
 
-Network device features:
+Network device features
+=======================
+
+::
 
 	%pNF	0x000000000000c000
 
-	For printing netdev_features_t.
+For printing netdev_features_t.
 
-	Passed by reference.
+Passed by reference.
 
-If you add other %p extensions, please extend lib/test_printf.c with
+If you add other ``%p`` extensions, please extend lib/test_printf.c with
 one or more test cases, if at all feasible.
 
 
 Thank you for your cooperation and attention.
-
-
-By Randy Dunlap <rdunlap@infradead.org> and
-Andrew Murray <amurray@mpc-data.co.uk>
-- 
2.9.4

[PATCH 05/29] pwm.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document title;
- mark literal blocks;
- better format the parameters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/pwm.txt | 46 ++++++++++++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt
index 789b27c6ec99..8fbf0aa3ba2d 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.txt
@@ -1,4 +1,6 @@
+======================================
 Pulse Width Modulation (PWM) interface
+======================================
 
 This provides an overview about the Linux PWM interface
 
@@ -16,7 +18,7 @@ Users of the legacy PWM API use unique IDs to refer to PWM devices.
 
 Instead of referring to a PWM device via its unique ID, board setup code
 should instead register a static mapping that can be used to match PWM
-consumers to providers, as given in the following example:
+consumers to providers, as given in the following example::
 
 	static struct pwm_lookup board_pwm_lookup[] = {
 		PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL,
@@ -40,9 +42,9 @@ New users should use the pwm_get() function and pass to it the consumer
 device or a consumer name. pwm_put() is used to free the PWM device. Managed
 variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist.
 
-After being requested, a PWM has to be configured using:
+After being requested, a PWM has to be configured using::
 
-int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
+	int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
 
 This API controls both the PWM period/duty_cycle config and the
 enable/disable state.
@@ -72,11 +74,14 @@ interface is provided to use the PWMs from userspace. It is exposed at
 pwmchipN, where N is the base of the PWM chip. Inside the directory you
 will find:
 
-npwm - The number of PWM channels this chip supports (read-only).
+  npwm
+    The number of PWM channels this chip supports (read-only).
 
-export - Exports a PWM channel for use with sysfs (write-only).
+  export
+    Exports a PWM channel for use with sysfs (write-only).
 
-unexport - Unexports a PWM channel from sysfs (write-only).
+  unexport
+   Unexports a PWM channel from sysfs (write-only).
 
 The PWM channels are numbered using a per-chip index from 0 to npwm-1.
 
@@ -84,21 +89,26 @@ When a PWM channel is exported a pwmX directory will be created in the
 pwmchipN directory it is associated with, where X is the number of the
 channel that was exported. The following properties will then be available:
 
-period - The total period of the PWM signal (read/write).
-	Value is in nanoseconds and is the sum of the active and inactive
-	time of the PWM.
+  period
+    The total period of the PWM signal (read/write).
+    Value is in nanoseconds and is the sum of the active and inactive
+    time of the PWM.
 
-duty_cycle - The active time of the PWM signal (read/write).
-	Value is in nanoseconds and must be less than the period.
+  duty_cycle
+    The active time of the PWM signal (read/write).
+    Value is in nanoseconds and must be less than the period.
 
-polarity - Changes the polarity of the PWM signal (read/write).
-	Writes to this property only work if the PWM chip supports changing
-	the polarity. The polarity can only be changed if the PWM is not
-	enabled. Value is the string "normal" or "inversed".
+  polarity
+    Changes the polarity of the PWM signal (read/write).
+    Writes to this property only work if the PWM chip supports changing
+    the polarity. The polarity can only be changed if the PWM is not
+    enabled. Value is the string "normal" or "inversed".
 
-enable - Enable/disable the PWM signal (read/write).
-	0 - disabled
-	1 - enabled
+  enable
+    Enable/disable the PWM signal (read/write).
+
+	- 0 - disabled
+	- 1 - enabled
 
 Implementing a PWM driver
 -------------------------
-- 
2.9.4

[PATCH 06/29] rbtree.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Mark document title;
- Use :Author: for authorship;
- mark a sub-section title as such;
- mark literal blocks;
- adjust identation where needed.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rbtree.txt | 88 +++++++++++++++++++++++++-----------------------
 1 file changed, 46 insertions(+), 42 deletions(-)

diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index b9d9cc57be18..b8a8c70b0188 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -1,7 +1,10 @@
+=================================
 Red-black Trees (rbtree) in Linux
-January 18, 2007
-Rob Landley <rob@landley.net>
-=============================
+=================================
+
+
+:Date: January 18, 2007
+:Author: Rob Landley <rob@landley.net>
 
 What are red-black trees, and what are they for?
 ------------------------------------------------
@@ -56,7 +59,7 @@ user of the rbtree code.
 Creating a new rbtree
 ---------------------
 
-Data nodes in an rbtree tree are structures containing a struct rb_node member:
+Data nodes in an rbtree tree are structures containing a struct rb_node member::
 
   struct mytype {
   	struct rb_node node;
@@ -78,7 +81,7 @@ Searching for a value in an rbtree
 Writing a search function for your tree is fairly straightforward: start at the
 root, compare each value, and follow the left or right branch as necessary.
 
-Example:
+Example::
 
   struct mytype *my_search(struct rb_root *root, char *string)
   {
@@ -110,7 +113,7 @@ The search for insertion differs from the previous search by finding the
 location of the pointer on which to graft the new node.  The new node also
 needs a link to its parent node for rebalancing purposes.
 
-Example:
+Example::
 
   int my_insert(struct rb_root *root, struct mytype *data)
   {
@@ -140,11 +143,11 @@ Example:
 Removing or replacing existing data in an rbtree
 ------------------------------------------------
 
-To remove an existing node from a tree, call:
+To remove an existing node from a tree, call::
 
   void rb_erase(struct rb_node *victim, struct rb_root *tree);
 
-Example:
+Example::
 
   struct mytype *data = mysearch(&mytree, "walrus");
 
@@ -153,7 +156,7 @@ Example:
   	myfree(data);
   }
 
-To replace an existing node in a tree with a new one with the same key, call:
+To replace an existing node in a tree with a new one with the same key, call::
 
   void rb_replace_node(struct rb_node *old, struct rb_node *new,
   			struct rb_root *tree);
@@ -166,7 +169,7 @@ Iterating through the elements stored in an rbtree (in sort order)
 
 Four functions are provided for iterating through an rbtree's contents in
 sorted order.  These work on arbitrary trees, and should not need to be
-modified or wrapped (except for locking purposes):
+modified or wrapped (except for locking purposes)::
 
   struct rb_node *rb_first(struct rb_root *tree);
   struct rb_node *rb_last(struct rb_root *tree);
@@ -184,7 +187,7 @@ which the containing data structure may be accessed with the container_of()
 macro, and individual members may be accessed directly via
 rb_entry(node, type, member).
 
-Example:
+Example::
 
   struct rb_node *node;
   for (node = rb_first(&mytree); node; node = rb_next(node))
@@ -241,7 +244,8 @@ user should have a single rb_erase_augmented() call site in order to limit
 compiled code size.
 
 
-Sample usage:
+Sample usage
+^^^^^^^^^^^^
 
 Interval tree is an example of augmented rb tree. Reference -
 "Introduction to Algorithms" by Cormen, Leiserson, Rivest and Stein.
@@ -259,12 +263,12 @@ This "extra information" stored in each node is the maximum hi
 information can be maintained at each node just be looking at the node
 and its immediate children. And this will be used in O(log n) lookup
 for lowest match (lowest start address among all possible matches)
-with something like:
+with something like::
 
-struct interval_tree_node *
-interval_tree_first_match(struct rb_root *root,
-			  unsigned long start, unsigned long last)
-{
+  struct interval_tree_node *
+  interval_tree_first_match(struct rb_root *root,
+			    unsigned long start, unsigned long last)
+  {
 	struct interval_tree_node *node;
 
 	if (!root->rb_node)
@@ -301,13 +305,13 @@ interval_tree_first_match(struct rb_root *root,
 		}
 		return NULL;	/* No match */
 	}
-}
+  }
 
-Insertion/removal are defined using the following augmented callbacks:
+Insertion/removal are defined using the following augmented callbacks::
 
-static inline unsigned long
-compute_subtree_last(struct interval_tree_node *node)
-{
+  static inline unsigned long
+  compute_subtree_last(struct interval_tree_node *node)
+  {
 	unsigned long max = node->last, subtree_last;
 	if (node->rb.rb_left) {
 		subtree_last = rb_entry(node->rb.rb_left,
@@ -322,10 +326,10 @@ compute_subtree_last(struct interval_tree_node *node)
 			max = subtree_last;
 	}
 	return max;
-}
+  }
 
-static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
-{
+  static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
+  {
 	while (rb != stop) {
 		struct interval_tree_node *node =
 			rb_entry(rb, struct interval_tree_node, rb);
@@ -335,20 +339,20 @@ static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
 		node->__subtree_last = subtree_last;
 		rb = rb_parent(&node->rb);
 	}
-}
+  }
 
-static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new)
-{
+  static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new)
+  {
 	struct interval_tree_node *old =
 		rb_entry(rb_old, struct interval_tree_node, rb);
 	struct interval_tree_node *new =
 		rb_entry(rb_new, struct interval_tree_node, rb);
 
 	new->__subtree_last = old->__subtree_last;
-}
+  }
 
-static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
-{
+  static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
+  {
 	struct interval_tree_node *old =
 		rb_entry(rb_old, struct interval_tree_node, rb);
 	struct interval_tree_node *new =
@@ -356,15 +360,15 @@ static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
 
 	new->__subtree_last = old->__subtree_last;
 	old->__subtree_last = compute_subtree_last(old);
-}
+  }
 
-static const struct rb_augment_callbacks augment_callbacks = {
+  static const struct rb_augment_callbacks augment_callbacks = {
 	augment_propagate, augment_copy, augment_rotate
-};
+  };
 
-void interval_tree_insert(struct interval_tree_node *node,
-			  struct rb_root *root)
-{
+  void interval_tree_insert(struct interval_tree_node *node,
+			    struct rb_root *root)
+  {
 	struct rb_node **link = &root->rb_node, *rb_parent = NULL;
 	unsigned long start = node->start, last = node->last;
 	struct interval_tree_node *parent;
@@ -383,10 +387,10 @@ void interval_tree_insert(struct interval_tree_node *node,
 	node->__subtree_last = last;
 	rb_link_node(&node->rb, rb_parent, link);
 	rb_insert_augmented(&node->rb, root, &augment_callbacks);
-}
+  }
 
-void interval_tree_remove(struct interval_tree_node *node,
-			  struct rb_root *root)
-{
+  void interval_tree_remove(struct interval_tree_node *node,
+			    struct rb_root *root)
+  {
 	rb_erase_augmented(&node->rb, root, &augment_callbacks);
-}
+  }
-- 
2.9.4

[PATCH 07/29] remoteproc.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document and section titles;
- adjust identation;
- mark literal blocks

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/remoteproc.txt | 320 +++++++++++++++++++++++++------------------
 1 file changed, 185 insertions(+), 135 deletions(-)

diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.txt
index f07597482351..77fb03acdbb4 100644
--- a/Documentation/remoteproc.txt
+++ b/Documentation/remoteproc.txt
@@ -1,6 +1,9 @@
+==========================
 Remote Processor Framework
+==========================
 
-1. Introduction
+Introduction
+============
 
 Modern SoCs typically have heterogeneous remote processor devices in asymmetric
 multiprocessing (AMP) configurations, which may be running different instances
@@ -26,44 +29,62 @@ remoteproc will add those devices. This makes it possible to reuse the
 existing virtio drivers with remote processor backends at a minimal development
 cost.
 
-2. User API
+User API
+========
+
+::
 
   int rproc_boot(struct rproc *rproc)
-    - Boot a remote processor (i.e. load its firmware, power it on, ...).
-      If the remote processor is already powered on, this function immediately
-      returns (successfully).
-      Returns 0 on success, and an appropriate error value otherwise.
-      Note: to use this function you should already have a valid rproc
-      handle. There are several ways to achieve that cleanly (devres, pdata,
-      the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
-      might also consider using dev_archdata for this).
+
+Boot a remote processor (i.e. load its firmware, power it on, ...).
+
+If the remote processor is already powered on, this function immediately
+returns (successfully).
+
+Returns 0 on success, and an appropriate error value otherwise.
+Note: to use this function you should already have a valid rproc
+handle. There are several ways to achieve that cleanly (devres, pdata,
+the way remoteproc_rpmsg.c does this, or, if this becomes prevalent, we
+might also consider using dev_archdata for this).
+
+::
 
   void rproc_shutdown(struct rproc *rproc)
-    - Power off a remote processor (previously booted with rproc_boot()).
-      In case @rproc is still being used by an additional user(s), then
-      this function will just decrement the power refcount and exit,
-      without really powering off the device.
-      Every call to rproc_boot() must (eventually) be accompanied by a call
-      to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
-      Notes:
-      - we're not decrementing the rproc's refcount, only the power refcount.
-        which means that the @rproc handle stays valid even after
-        rproc_shutdown() returns, and users can still use it with a subsequent
-        rproc_boot(), if needed.
+
+Power off a remote processor (previously booted with rproc_boot()).
+In case @rproc is still being used by an additional user(s), then
+this function will just decrement the power refcount and exit,
+without really powering off the device.
+
+Every call to rproc_boot() must (eventually) be accompanied by a call
+to rproc_shutdown(). Calling rproc_shutdown() redundantly is a bug.
+
+.. note::
+
+  we're not decrementing the rproc's refcount, only the power refcount.
+  which means that the @rproc handle stays valid even after
+  rproc_shutdown() returns, and users can still use it with a subsequent
+  rproc_boot(), if needed.
+
+::
 
   struct rproc *rproc_get_by_phandle(phandle phandle)
-    - Find an rproc handle using a device tree phandle. Returns the rproc
-      handle on success, and NULL on failure. This function increments
-      the remote processor's refcount, so always use rproc_put() to
-      decrement it back once rproc isn't needed anymore.
 
-3. Typical usage
+Find an rproc handle using a device tree phandle. Returns the rproc
+handle on success, and NULL on failure. This function increments
+the remote processor's refcount, so always use rproc_put() to
+decrement it back once rproc isn't needed anymore.
 
-#include <linux/remoteproc.h>
+Typical usage
+=============
 
-/* in case we were given a valid 'rproc' handle */
-int dummy_rproc_example(struct rproc *my_rproc)
-{
+::
+
+  #include <linux/remoteproc.h>
+
+  /* in case we were given a valid 'rproc' handle */
+  int dummy_rproc_example(struct rproc *my_rproc)
+  {
 	int ret;
 
 	/* let's power on and boot our remote processor */
@@ -80,84 +101,111 @@ int dummy_rproc_example(struct rproc *my_rproc)
 
 	/* let's shut it down now */
 	rproc_shutdown(my_rproc);
-}
+  }
 
-4. API for implementors
+API for implementors
+====================
+
+::
 
   struct rproc *rproc_alloc(struct device *dev, const char *name,
 				const struct rproc_ops *ops,
 				const char *firmware, int len)
-    - Allocate a new remote processor handle, but don't register
-      it yet. Required parameters are the underlying device, the
-      name of this remote processor, platform-specific ops handlers,
-      the name of the firmware to boot this rproc with, and the
-      length of private data needed by the allocating rproc driver (in bytes).
-
-      This function should be used by rproc implementations during
-      initialization of the remote processor.
-      After creating an rproc handle using this function, and when ready,
-      implementations should then call rproc_add() to complete
-      the registration of the remote processor.
-      On success, the new rproc is returned, and on failure, NULL.
-
-      Note: _never_ directly deallocate @rproc, even if it was not registered
-      yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
+
+Allocate a new remote processor handle, but don't register
+it yet. Required parameters are the underlying device, the
+name of this remote processor, platform-specific ops handlers,
+the name of the firmware to boot this rproc with, and the
+length of private data needed by the allocating rproc driver (in bytes).
+
+This function should be used by rproc implementations during
+initialization of the remote processor.
+
+After creating an rproc handle using this function, and when ready,
+implementations should then call rproc_add() to complete
+the registration of the remote processor.
+
+On success, the new rproc is returned, and on failure, NULL.
+
+.. note::
+
+  **never** directly deallocate @rproc, even if it was not registered
+  yet. Instead, when you need to unroll rproc_alloc(), use rproc_free().
+
+::
 
   void rproc_free(struct rproc *rproc)
-    - Free an rproc handle that was allocated by rproc_alloc.
-      This function essentially unrolls rproc_alloc(), by decrementing the
-      rproc's refcount. It doesn't directly free rproc; that would happen
-      only if there are no other references to rproc and its refcount now
-      dropped to zero.
+
+Free an rproc handle that was allocated by rproc_alloc.
+
+This function essentially unrolls rproc_alloc(), by decrementing the
+rproc's refcount. It doesn't directly free rproc; that would happen
+only if there are no other references to rproc and its refcount now
+dropped to zero.
+
+::
 
   int rproc_add(struct rproc *rproc)
-    - Register @rproc with the remoteproc framework, after it has been
-      allocated with rproc_alloc().
-      This is called by the platform-specific rproc implementation, whenever
-      a new remote processor device is probed.
-      Returns 0 on success and an appropriate error code otherwise.
-      Note: this function initiates an asynchronous firmware loading
-      context, which will look for virtio devices supported by the rproc's
-      firmware.
-      If found, those virtio devices will be created and added, so as a result
-      of registering this remote processor, additional virtio drivers might get
-      probed.
+
+Register @rproc with the remoteproc framework, after it has been
+allocated with rproc_alloc().
+
+This is called by the platform-specific rproc implementation, whenever
+a new remote processor device is probed.
+
+Returns 0 on success and an appropriate error code otherwise.
+Note: this function initiates an asynchronous firmware loading
+context, which will look for virtio devices supported by the rproc's
+firmware.
+
+If found, those virtio devices will be created and added, so as a result
+of registering this remote processor, additional virtio drivers might get
+probed.
+
+::
 
   int rproc_del(struct rproc *rproc)
-    - Unroll rproc_add().
-      This function should be called when the platform specific rproc
-      implementation decides to remove the rproc device. it should
-      _only_ be called if a previous invocation of rproc_add()
-      has completed successfully.
 
-      After rproc_del() returns, @rproc is still valid, and its
-      last refcount should be decremented by calling rproc_free().
+Unroll rproc_add().
 
-      Returns 0 on success and -EINVAL if @rproc isn't valid.
+This function should be called when the platform specific rproc
+implementation decides to remove the rproc device. it should
+_only_ be called if a previous invocation of rproc_add()
+has completed successfully.
+
+After rproc_del() returns, @rproc is still valid, and its
+last refcount should be decremented by calling rproc_free().
+
+Returns 0 on success and -EINVAL if @rproc isn't valid.
+
+::
 
   void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type)
-    - Report a crash in a remoteproc
-      This function must be called every time a crash is detected by the
-      platform specific rproc implementation. This should not be called from a
-      non-remoteproc driver. This function can be called from atomic/interrupt
-      context.
 
-5. Implementation callbacks
+Report a crash in a remoteproc
+
+This function must be called every time a crash is detected by the
+platform specific rproc implementation. This should not be called from a
+non-remoteproc driver. This function can be called from atomic/interrupt
+context.
+
+Implementation callbacks
+========================
 
 These callbacks should be provided by platform-specific remoteproc
-drivers:
+drivers::
 
-/**
- * struct rproc_ops - platform-specific device handlers
- * @start:	power on the device and boot it
- * @stop:	power off the device
- * @kick:	kick a virtqueue (virtqueue id given as a parameter)
- */
-struct rproc_ops {
+  /**
+   * struct rproc_ops - platform-specific device handlers
+   * @start:	power on the device and boot it
+   * @stop:	power off the device
+   * @kick:	kick a virtqueue (virtqueue id given as a parameter)
+   */
+  struct rproc_ops {
 	int (*start)(struct rproc *rproc);
 	int (*stop)(struct rproc *rproc);
 	void (*kick)(struct rproc *rproc, int vqid);
-};
+  };
 
 Every remoteproc implementation should at least provide the ->start and ->stop
 handlers. If rpmsg/virtio functionality is also desired, then the ->kick handler
@@ -179,7 +227,8 @@ the exact virtqueue index to look in is optional: it is easy (and not
 too expensive) to go through the existing virtqueues and look for new buffers
 in the used rings.
 
-6. Binary Firmware Structure
+Binary Firmware Structure
+=========================
 
 At this point remoteproc only supports ELF32 firmware binaries. However,
 it is quite expected that other platforms/devices which we'd want to
@@ -207,43 +256,43 @@ resource entries that publish the existence of supported features
 or configurations by the remote processor, such as trace buffers and
 supported virtio devices (and their configurations).
 
-The resource table begins with this header:
+The resource table begins with this header::
 
-/**
- * struct resource_table - firmware resource table header
- * @ver: version number
- * @num: number of resource entries
- * @reserved: reserved (must be zero)
- * @offset: array of offsets pointing at the various resource entries
- *
- * The header of the resource table, as expressed by this structure,
- * contains a version number (should we need to change this format in the
- * future), the number of available resource entries, and their offsets
- * in the table.
- */
-struct resource_table {
+  /**
+   * struct resource_table - firmware resource table header
+   * @ver: version number
+   * @num: number of resource entries
+   * @reserved: reserved (must be zero)
+   * @offset: array of offsets pointing at the various resource entries
+   *
+   * The header of the resource table, as expressed by this structure,
+   * contains a version number (should we need to change this format in the
+   * future), the number of available resource entries, and their offsets
+   * in the table.
+   */
+  struct resource_table {
 	u32 ver;
 	u32 num;
 	u32 reserved[2];
 	u32 offset[0];
-} __packed;
+  } __packed;
 
 Immediately following this header are the resource entries themselves,
-each of which begins with the following resource entry header:
+each of which begins with the following resource entry header::
 
-/**
- * struct fw_rsc_hdr - firmware resource entry header
- * @type: resource type
- * @data: resource data
- *
- * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
- * its @type. The content of the entry itself will immediately follow
- * this header, and it should be parsed according to the resource type.
- */
-struct fw_rsc_hdr {
+  /**
+   * struct fw_rsc_hdr - firmware resource entry header
+   * @type: resource type
+   * @data: resource data
+   *
+   * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
+   * its @type. The content of the entry itself will immediately follow
+   * this header, and it should be parsed according to the resource type.
+   */
+  struct fw_rsc_hdr {
 	u32 type;
 	u8 data[0];
-} __packed;
+  } __packed;
 
 Some resources entries are mere announcements, where the host is informed
 of specific remoteproc configuration. Other entries require the host to
@@ -252,32 +301,32 @@ is expected, where the firmware requests a resource, and once allocated,
 the host should provide back its details (e.g. address of an allocated
 memory region).
 
-Here are the various resource types that are currently supported:
+Here are the various resource types that are currently supported::
 
-/**
- * enum fw_resource_type - types of resource entries
- *
- * @RSC_CARVEOUT:   request for allocation of a physically contiguous
- *		    memory region.
- * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
- * @RSC_TRACE:	    announces the availability of a trace buffer into which
- *		    the remote processor will be writing logs.
- * @RSC_VDEV:       declare support for a virtio device, and serve as its
- *		    virtio header.
- * @RSC_LAST:       just keep this one at the end
- *
- * Please note that these values are used as indices to the rproc_handle_rsc
- * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
- * check the validity of an index before the lookup table is accessed, so
- * please update it as needed.
- */
-enum fw_resource_type {
+  /**
+   * enum fw_resource_type - types of resource entries
+   *
+   * @RSC_CARVEOUT:   request for allocation of a physically contiguous
+   *		    memory region.
+   * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
+   * @RSC_TRACE:	    announces the availability of a trace buffer into which
+   *		    the remote processor will be writing logs.
+   * @RSC_VDEV:       declare support for a virtio device, and serve as its
+   *		    virtio header.
+   * @RSC_LAST:       just keep this one at the end
+   *
+   * Please note that these values are used as indices to the rproc_handle_rsc
+   * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
+   * check the validity of an index before the lookup table is accessed, so
+   * please update it as needed.
+   */
+  enum fw_resource_type {
 	RSC_CARVEOUT	= 0,
 	RSC_DEVMEM	= 1,
 	RSC_TRACE	= 2,
 	RSC_VDEV	= 3,
 	RSC_LAST	= 4,
-};
+  };
 
 For more details regarding a specific resource type, please see its
 dedicated structure in include/linux/remoteproc.h.
@@ -286,7 +335,8 @@ We also expect that platform-specific resource entries will show up
 at some point. When that happens, we could easily add a new RSC_PLATFORM
 type, and hand those resources to the platform-specific rproc driver to handle.
 
-7. Virtio and remoteproc
+Virtio and remoteproc
+=====================
 
 The firmware should provide remoteproc information about virtio devices
 that it supports, and their configurations: a RSC_VDEV resource entry
-- 
2.9.4

[PATCH 08/29] rfkill.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark titles;
- comment contents index;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rfkill.txt | 47 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index 8c174063b3f0..d22feccedbd1 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -1,13 +1,17 @@
+===============================
 rfkill - RF kill switch support
 ===============================
 
-1. Introduction
-2. Implementation details
-3. Kernel API
-4. Userspace support
+.. CONTENTS
 
+  1. Introduction
+  2. Implementation details
+  3. Kernel API
+  4. Userspace support
 
-1. Introduction
+
+Introduction
+============
 
 The rfkill subsystem provides a generic interface to disabling any radio
 transmitter in the system. When a transmitter is blocked, it shall not
@@ -21,17 +25,24 @@ aircraft.
 The rfkill subsystem has a concept of "hard" and "soft" block, which
 differ little in their meaning (block == transmitters off) but rather in
 whether they can be changed or not:
- - hard block: read-only radio block that cannot be overridden by software
- - soft block: writable radio block (need not be readable) that is set by
-               the system software.
+
+ - hard block
+	read-only radio block that cannot be overridden by software
+
+ - soft block
+	writable radio block (need not be readable) that is set by
+        the system software.
 
 The rfkill subsystem has two parameters, rfkill.default_state and
-rfkill.master_switch_mode, which are documented in admin-guide/kernel-parameters.rst.
+rfkill.master_switch_mode, which are documented in
+admin-guide/kernel-parameters.rst.
 
 
-2. Implementation details
+Implementation details
+======================
 
 The rfkill subsystem is composed of three main components:
+
  * the rfkill core,
  * the deprecated rfkill-input module (an input layer handler, being
    replaced by userspace policy code) and
@@ -55,7 +66,8 @@ use the return value of rfkill_set_hw_state() unless the hardware actually
 keeps track of soft and hard block separately.
 
 
-3. Kernel API
+Kernel API
+==========
 
 
 Drivers for radio transmitters normally implement an rfkill driver.
@@ -69,7 +81,7 @@ For some platforms, it is possible that the hardware state changes during
 suspend/hibernation, in which case it will be necessary to update the rfkill
 core with the current state is at resume time.
 
-To create an rfkill driver, driver's Kconfig needs to have
+To create an rfkill driver, driver's Kconfig needs to have::
 
 	depends on RFKILL || !RFKILL
 
@@ -87,7 +99,8 @@ RFKill provides per-switch LED triggers, which can be used to drive LEDs
 according to the switch state (LED_FULL when blocked, LED_OFF otherwise).
 
 
-5. Userspace support
+Userspace support
+=================
 
 The recommended userspace interface to use is /dev/rfkill, which is a misc
 character device that allows userspace to obtain and set the state of rfkill
@@ -112,11 +125,11 @@ rfkill core framework.
 Additionally, each rfkill device is registered in sysfs and emits uevents.
 
 rfkill devices issue uevents (with an action of "change"), with the following
-environment variables set:
+environment variables set::
 
-RFKILL_NAME
-RFKILL_STATE
-RFKILL_TYPE
+	RFKILL_NAME
+	RFKILL_STATE
+	RFKILL_TYPE
 
 The contents of these variables corresponds to the "name", "state" and
 "type" sysfs files explained above.
-- 
2.9.4

[PATCH 09/29] robust-futex-ABI.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- promote document title;
- use :Author: for authorship;
- mark literal blocks;
- add blank lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/robust-futex-ABI.txt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.txt
index 16eb314f56cc..8a5d34abf726 100644
--- a/Documentation/robust-futex-ABI.txt
+++ b/Documentation/robust-futex-ABI.txt
@@ -1,7 +1,9 @@
-Started by Paul Jackson <pj@sgi.com>
-
+====================
 The robust futex ABI
---------------------
+====================
+
+:Author: Started by Paul Jackson <pj@sgi.com>
+
 
 Robust_futexes provide a mechanism that is used in addition to normal
 futexes, for kernel assist of cleanup of held locks on task exit.
@@ -32,7 +34,7 @@ probably causing deadlock or other such failure of the other threads
 waiting on the same locks.
 
 A thread that anticipates possibly using robust_futexes should first
-issue the system call:
+issue the system call::
 
     asmlinkage long
     sys_set_robust_list(struct robust_list_head __user *head, size_t len);
@@ -91,7 +93,7 @@ that lock using the futex mechanism.
 When a thread has invoked the above system call to indicate it
 anticipates using robust_futexes, the kernel stores the passed in 'head'
 pointer for that task.  The task may retrieve that value later on by
-using the system call:
+using the system call::
 
     asmlinkage long
     sys_get_robust_list(int pid, struct robust_list_head __user **head_ptr,
@@ -135,6 +137,7 @@ manipulating this list), the user code must observe the following
 protocol on 'lock entry' insertion and removal:
 
 On insertion:
+
  1) set the 'list_op_pending' word to the address of the 'lock entry'
     to be inserted,
  2) acquire the futex lock,
@@ -143,6 +146,7 @@ On insertion:
  4) clear the 'list_op_pending' word.
 
 On removal:
+
  1) set the 'list_op_pending' word to the address of the 'lock entry'
     to be removed,
  2) remove the lock entry for this lock from the 'head' list,
-- 
2.9.4

[PATCH 10/29] robust-futexes.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- add a title for the document;
- mark literal blocks;

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/robust-futexes.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.txt
index 61c22d608759..6c42c75103eb 100644
--- a/Documentation/robust-futexes.txt
+++ b/Documentation/robust-futexes.txt
@@ -1,4 +1,8 @@
-Started by: Ingo Molnar <mingo@redhat.com>
+========================================
+A description of what robust futexes are
+========================================
+
+:Started by: Ingo Molnar <mingo@redhat.com>
 
 Background
 ----------
@@ -163,7 +167,7 @@ Implementation details
 ----------------------
 
 The patch adds two new syscalls: one to register the userspace list, and
-one to query the registered list pointer:
+one to query the registered list pointer::
 
  asmlinkage long
  sys_set_robust_list(struct robust_list_head __user *head,
@@ -185,7 +189,7 @@ straightforward. The kernel doesn't have any internal distinction between
 robust and normal futexes.
 
 If a futex is found to be held at exit time, the kernel sets the
-following bit of the futex word:
+following bit of the futex word::
 
 	#define FUTEX_OWNER_DIED        0x40000000
 
@@ -193,7 +197,7 @@ and wakes up the next futex waiter (if any). User-space does the rest of
 the cleanup.
 
 Otherwise, robust futexes are acquired by glibc by putting the TID into
-the futex field atomically. Waiters set the FUTEX_WAITERS bit:
+the futex field atomically. Waiters set the FUTEX_WAITERS bit::
 
 	#define FUTEX_WAITERS           0x80000000
 
-- 
2.9.4

[PATCH 11/29] rpmsg.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document and chapter titles;
- mark notes;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rpmsg.txt | 340 ++++++++++++++++++++++++++++--------------------
 1 file changed, 200 insertions(+), 140 deletions(-)

diff --git a/Documentation/rpmsg.txt b/Documentation/rpmsg.txt
index a95e36a43288..24b7a9e1a5f9 100644
--- a/Documentation/rpmsg.txt
+++ b/Documentation/rpmsg.txt
@@ -1,10 +1,15 @@
+============================================
 Remote Processor Messaging (rpmsg) Framework
+============================================
 
-Note: this document describes the rpmsg bus and how to write rpmsg drivers.
-To learn how to add rpmsg support for new platforms, check out remoteproc.txt
-(also a resident of Documentation/).
+.. note::
 
-1. Introduction
+  This document describes the rpmsg bus and how to write rpmsg drivers.
+  To learn how to add rpmsg support for new platforms, check out remoteproc.txt
+  (also a resident of Documentation/).
+
+Introduction
+============
 
 Modern SoCs typically employ heterogeneous remote processor devices in
 asymmetric multiprocessing (AMP) configurations, which may be running
@@ -58,170 +63,222 @@ to their destination address (this is done by invoking the driver's rx handler
 with the payload of the inbound message).
 
 
-2. User API
+User API
+========
+
+::
 
   int rpmsg_send(struct rpmsg_channel *rpdev, void *data, int len);
-   - sends a message across to the remote processor on a given channel.
-     The caller should specify the channel, the data it wants to send,
-     and its length (in bytes). The message will be sent on the specified
-     channel, i.e. its source and destination address fields will be
-     set to the channel's src and dst addresses.
-
-     In case there are no TX buffers available, the function will block until
-     one becomes available (i.e. until the remote processor consumes
-     a tx buffer and puts it back on virtio's used descriptor ring),
-     or a timeout of 15 seconds elapses. When the latter happens,
-     -ERESTARTSYS is returned.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+sends a message across to the remote processor on a given channel.
+The caller should specify the channel, the data it wants to send,
+and its length (in bytes). The message will be sent on the specified
+channel, i.e. its source and destination address fields will be
+set to the channel's src and dst addresses.
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   int rpmsg_sendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst);
-   - sends a message across to the remote processor on a given channel,
-     to a destination address provided by the caller.
-     The caller should specify the channel, the data it wants to send,
-     its length (in bytes), and an explicit destination address.
-     The message will then be sent to the remote processor to which the
-     channel belongs, using the channel's src address, and the user-provided
-     dst address (thus the channel's dst address will be ignored).
-
-     In case there are no TX buffers available, the function will block until
-     one becomes available (i.e. until the remote processor consumes
-     a tx buffer and puts it back on virtio's used descriptor ring),
-     or a timeout of 15 seconds elapses. When the latter happens,
-     -ERESTARTSYS is returned.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+sends a message across to the remote processor on a given channel,
+to a destination address provided by the caller.
+
+The caller should specify the channel, the data it wants to send,
+its length (in bytes), and an explicit destination address.
+
+The message will then be sent to the remote processor to which the
+channel belongs, using the channel's src address, and the user-provided
+dst address (thus the channel's dst address will be ignored).
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   int rpmsg_send_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
 							void *data, int len);
-   - sends a message across to the remote processor, using the src and dst
-     addresses provided by the user.
-     The caller should specify the channel, the data it wants to send,
-     its length (in bytes), and explicit source and destination addresses.
-     The message will then be sent to the remote processor to which the
-     channel belongs, but the channel's src and dst addresses will be
-     ignored (and the user-provided addresses will be used instead).
-
-     In case there are no TX buffers available, the function will block until
-     one becomes available (i.e. until the remote processor consumes
-     a tx buffer and puts it back on virtio's used descriptor ring),
-     or a timeout of 15 seconds elapses. When the latter happens,
-     -ERESTARTSYS is returned.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+
+sends a message across to the remote processor, using the src and dst
+addresses provided by the user.
+
+The caller should specify the channel, the data it wants to send,
+its length (in bytes), and explicit source and destination addresses.
+The message will then be sent to the remote processor to which the
+channel belongs, but the channel's src and dst addresses will be
+ignored (and the user-provided addresses will be used instead).
+
+In case there are no TX buffers available, the function will block until
+one becomes available (i.e. until the remote processor consumes
+a tx buffer and puts it back on virtio's used descriptor ring),
+or a timeout of 15 seconds elapses. When the latter happens,
+-ERESTARTSYS is returned.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   int rpmsg_trysend(struct rpmsg_channel *rpdev, void *data, int len);
-   - sends a message across to the remote processor on a given channel.
-     The caller should specify the channel, the data it wants to send,
-     and its length (in bytes). The message will be sent on the specified
-     channel, i.e. its source and destination address fields will be
-     set to the channel's src and dst addresses.
-
-     In case there are no TX buffers available, the function will immediately
-     return -ENOMEM without waiting until one becomes available.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+sends a message across to the remote processor on a given channel.
+The caller should specify the channel, the data it wants to send,
+and its length (in bytes). The message will be sent on the specified
+channel, i.e. its source and destination address fields will be
+set to the channel's src and dst addresses.
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   int rpmsg_trysendto(struct rpmsg_channel *rpdev, void *data, int len, u32 dst)
-   - sends a message across to the remote processor on a given channel,
-     to a destination address provided by the user.
-     The user should specify the channel, the data it wants to send,
-     its length (in bytes), and an explicit destination address.
-     The message will then be sent to the remote processor to which the
-     channel belongs, using the channel's src address, and the user-provided
-     dst address (thus the channel's dst address will be ignored).
-
-     In case there are no TX buffers available, the function will immediately
-     return -ENOMEM without waiting until one becomes available.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+
+sends a message across to the remote processor on a given channel,
+to a destination address provided by the user.
+
+The user should specify the channel, the data it wants to send,
+its length (in bytes), and an explicit destination address.
+
+The message will then be sent to the remote processor to which the
+channel belongs, using the channel's src address, and the user-provided
+dst address (thus the channel's dst address will be ignored).
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   int rpmsg_trysend_offchannel(struct rpmsg_channel *rpdev, u32 src, u32 dst,
 							void *data, int len);
-   - sends a message across to the remote processor, using source and
-     destination addresses provided by the user.
-     The user should specify the channel, the data it wants to send,
-     its length (in bytes), and explicit source and destination addresses.
-     The message will then be sent to the remote processor to which the
-     channel belongs, but the channel's src and dst addresses will be
-     ignored (and the user-provided addresses will be used instead).
-
-     In case there are no TX buffers available, the function will immediately
-     return -ENOMEM without waiting until one becomes available.
-     The function can only be called from a process context (for now).
-     Returns 0 on success and an appropriate error value on failure.
+
+
+sends a message across to the remote processor, using source and
+destination addresses provided by the user.
+
+The user should specify the channel, the data it wants to send,
+its length (in bytes), and explicit source and destination addresses.
+The message will then be sent to the remote processor to which the
+channel belongs, but the channel's src and dst addresses will be
+ignored (and the user-provided addresses will be used instead).
+
+In case there are no TX buffers available, the function will immediately
+return -ENOMEM without waiting until one becomes available.
+
+The function can only be called from a process context (for now).
+Returns 0 on success and an appropriate error value on failure.
+
+::
 
   struct rpmsg_endpoint *rpmsg_create_ept(struct rpmsg_channel *rpdev,
 		void (*cb)(struct rpmsg_channel *, void *, int, void *, u32),
 		void *priv, u32 addr);
-   - every rpmsg address in the system is bound to an rx callback (so when
-     inbound messages arrive, they are dispatched by the rpmsg bus using the
-     appropriate callback handler) by means of an rpmsg_endpoint struct.
 
-     This function allows drivers to create such an endpoint, and by that,
-     bind a callback, and possibly some private data too, to an rpmsg address
-     (either one that is known in advance, or one that will be dynamically
-     assigned for them).
+every rpmsg address in the system is bound to an rx callback (so when
+inbound messages arrive, they are dispatched by the rpmsg bus using the
+appropriate callback handler) by means of an rpmsg_endpoint struct.
 
-     Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
-     is already created for them when they are probed by the rpmsg bus
-     (using the rx callback they provide when they registered to the rpmsg bus).
+This function allows drivers to create such an endpoint, and by that,
+bind a callback, and possibly some private data too, to an rpmsg address
+(either one that is known in advance, or one that will be dynamically
+assigned for them).
 
-     So things should just work for simple drivers: they already have an
-     endpoint, their rx callback is bound to their rpmsg address, and when
-     relevant inbound messages arrive (i.e. messages which their dst address
-     equals to the src address of their rpmsg channel), the driver's handler
-     is invoked to process it.
+Simple rpmsg drivers need not call rpmsg_create_ept, because an endpoint
+is already created for them when they are probed by the rpmsg bus
+(using the rx callback they provide when they registered to the rpmsg bus).
 
-     That said, more complicated drivers might do need to allocate
-     additional rpmsg addresses, and bind them to different rx callbacks.
-     To accomplish that, those drivers need to call this function.
-     Drivers should provide their channel (so the new endpoint would bind
-     to the same remote processor their channel belongs to), an rx callback
-     function, an optional private data (which is provided back when the
-     rx callback is invoked), and an address they want to bind with the
-     callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
-     dynamically assign them an available rpmsg address (drivers should have
-     a very good reason why not to always use RPMSG_ADDR_ANY here).
+So things should just work for simple drivers: they already have an
+endpoint, their rx callback is bound to their rpmsg address, and when
+relevant inbound messages arrive (i.e. messages which their dst address
+equals to the src address of their rpmsg channel), the driver's handler
+is invoked to process it.
 
-     Returns a pointer to the endpoint on success, or NULL on error.
+That said, more complicated drivers might do need to allocate
+additional rpmsg addresses, and bind them to different rx callbacks.
+To accomplish that, those drivers need to call this function.
+Drivers should provide their channel (so the new endpoint would bind
+to the same remote processor their channel belongs to), an rx callback
+function, an optional private data (which is provided back when the
+rx callback is invoked), and an address they want to bind with the
+callback. If addr is RPMSG_ADDR_ANY, then rpmsg_create_ept will
+dynamically assign them an available rpmsg address (drivers should have
+a very good reason why not to always use RPMSG_ADDR_ANY here).
+
+Returns a pointer to the endpoint on success, or NULL on error.
+
+::
 
   void rpmsg_destroy_ept(struct rpmsg_endpoint *ept);
-   - destroys an existing rpmsg endpoint. user should provide a pointer
-     to an rpmsg endpoint that was previously created with rpmsg_create_ept().
+
+
+destroys an existing rpmsg endpoint. user should provide a pointer
+to an rpmsg endpoint that was previously created with rpmsg_create_ept().
+
+::
 
   int register_rpmsg_driver(struct rpmsg_driver *rpdrv);
-   - registers an rpmsg driver with the rpmsg bus. user should provide
-     a pointer to an rpmsg_driver struct, which contains the driver's
-     ->probe() and ->remove() functions, an rx callback, and an id_table
-     specifying the names of the channels this driver is interested to
-     be probed with.
+
+
+registers an rpmsg driver with the rpmsg bus. user should provide
+a pointer to an rpmsg_driver struct, which contains the driver's
+->probe() and ->remove() functions, an rx callback, and an id_table
+specifying the names of the channels this driver is interested to
+be probed with.
+
+::
 
   void unregister_rpmsg_driver(struct rpmsg_driver *rpdrv);
-   - unregisters an rpmsg driver from the rpmsg bus. user should provide
-     a pointer to a previously-registered rpmsg_driver struct.
-     Returns 0 on success, and an appropriate error value on failure.
 
 
-3. Typical usage
+unregisters an rpmsg driver from the rpmsg bus. user should provide
+a pointer to a previously-registered rpmsg_driver struct.
+Returns 0 on success, and an appropriate error value on failure.
+
+
+Typical usage
+=============
 
 The following is a simple rpmsg driver, that sends an "hello!" message
 on probe(), and whenever it receives an incoming message, it dumps its
 content to the console.
 
-#include <linux/kernel.h>
-#include <linux/module.h>
-#include <linux/rpmsg.h>
+::
 
-static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
+  #include <linux/kernel.h>
+  #include <linux/module.h>
+  #include <linux/rpmsg.h>
+
+  static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
 						void *priv, u32 src)
-{
+  {
 	print_hex_dump(KERN_INFO, "incoming message:", DUMP_PREFIX_NONE,
 						16, 1, data, len, true);
-}
+  }
 
-static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
-{
+  static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
+  {
 	int err;
 
 	dev_info(&rpdev->dev, "chnl: 0x%x -> 0x%x\n", rpdev->src, rpdev->dst);
@@ -234,32 +291,35 @@ static int rpmsg_sample_probe(struct rpmsg_channel *rpdev)
 	}
 
 	return 0;
-}
+  }
 
-static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
-{
+  static void rpmsg_sample_remove(struct rpmsg_channel *rpdev)
+  {
 	dev_info(&rpdev->dev, "rpmsg sample client driver is removed\n");
-}
+  }
 
-static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
+  static struct rpmsg_device_id rpmsg_driver_sample_id_table[] = {
 	{ .name	= "rpmsg-client-sample" },
 	{ },
-};
-MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
+  };
+  MODULE_DEVICE_TABLE(rpmsg, rpmsg_driver_sample_id_table);
 
-static struct rpmsg_driver rpmsg_sample_client = {
+  static struct rpmsg_driver rpmsg_sample_client = {
 	.drv.name	= KBUILD_MODNAME,
 	.id_table	= rpmsg_driver_sample_id_table,
 	.probe		= rpmsg_sample_probe,
 	.callback	= rpmsg_sample_cb,
 	.remove		= rpmsg_sample_remove,
-};
-module_rpmsg_driver(rpmsg_sample_client);
+  };
+  module_rpmsg_driver(rpmsg_sample_client);
 
-Note: a similar sample which can be built and loaded can be found
-in samples/rpmsg/.
+.. note::
 
-4. Allocations of rpmsg channels:
+   a similar sample which can be built and loaded can be found
+   in samples/rpmsg/.
+
+Allocations of rpmsg channels
+=============================
 
 At this point we only support dynamic allocations of rpmsg channels.
 
-- 
2.9.4

[PATCH 12/29] rtc.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- adjust identation of the titles;
- mark a table as such;
- don't capitalize chapter names.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rtc.txt | 44 +++++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index ddc366026e00..47feb4414b7e 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -1,6 +1,6 @@
-
-	Real Time Clock (RTC) Drivers for Linux
-	=======================================
+=======================================
+Real Time Clock (RTC) Drivers for Linux
+=======================================
 
 When Linux developers talk about a "Real Time Clock", they usually mean
 something that tracks wall clock time and is battery backed so that it
@@ -32,8 +32,8 @@ only issue an alarm up to 24 hours in the future, other hardware may
 be able to schedule one any time in the upcoming century.
 
 
-	Old PC/AT-Compatible driver:  /dev/rtc
-	--------------------------------------
+Old PC/AT-Compatible driver:  /dev/rtc
+--------------------------------------
 
 All PCs (even Alpha machines) have a Real Time Clock built into them.
 Usually they are built into the chipset of the computer, but some may
@@ -105,8 +105,8 @@ that will be using this driver.  See the code at the end of this document.
 (The original /dev/rtc driver was written by Paul Gortmaker.)
 
 
-	New portable "RTC Class" drivers:  /dev/rtcN
-	--------------------------------------------
+New portable "RTC Class" drivers:  /dev/rtcN
+--------------------------------------------
 
 Because Linux supports many non-ACPI and non-PC platforms, some of which
 have more than one RTC style clock, it needed a more portable solution
@@ -136,35 +136,37 @@ a high functionality RTC is integrated into the SOC.  That system might read
 the system clock from the discrete RTC, but use the integrated one for all
 other tasks, because of its greater functionality.
 
-SYSFS INTERFACE
+SYSFS interface
 ---------------
 
 The sysfs interface under /sys/class/rtc/rtcN provides access to various
 rtc attributes without requiring the use of ioctls. All dates and times
 are in the RTC's timezone, rather than in system time.
 
-date:  	   	 RTC-provided date
-hctosys:   	 1 if the RTC provided the system time at boot via the
+================ ==============================================================
+date  	   	 RTC-provided date
+hctosys   	 1 if the RTC provided the system time at boot via the
 		 CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
-max_user_freq:	 The maximum interrupt rate an unprivileged user may request
+max_user_freq	 The maximum interrupt rate an unprivileged user may request
 		 from this RTC.
-name:		 The name of the RTC corresponding to this sysfs directory
-since_epoch:	 The number of seconds since the epoch according to the RTC
-time:		 RTC-provided time
-wakealarm:	 The time at which the clock will generate a system wakeup
+name		 The name of the RTC corresponding to this sysfs directory
+since_epoch	 The number of seconds since the epoch according to the RTC
+time		 RTC-provided time
+wakealarm	 The time at which the clock will generate a system wakeup
 		 event. This is a one shot wakeup event, so must be reset
-		 after wake if a daily wakeup is required. Format is seconds since
-		 the epoch by default, or if there's a leading +, seconds in the
-		 future, or if there is a leading +=, seconds ahead of the current
-		 alarm.
-offset:		 The amount which the rtc clock has been adjusted in firmware.
+		 after wake if a daily wakeup is required. Format is seconds
+		 since the epoch by default, or if there's a leading +, seconds
+		 in the future, or if there is a leading +=, seconds ahead of
+		 the current alarm.
+offset		 The amount which the rtc clock has been adjusted in firmware.
 		 Visible only if the driver supports clock offset adjustment.
 		 The unit is parts per billion, i.e. The number of clock ticks
 		 which are added to or removed from the rtc's base clock per
 		 billion ticks. A positive value makes a day pass more slowly,
 		 longer, and a negative value makes a day pass more quickly.
+================ ==============================================================
 
-IOCTL INTERFACE
+IOCTL interface
 ---------------
 
 The ioctl() calls supported by /dev/rtc are also supported by the RTC class
-- 
2.9.4

[rtc-linux] [PATCH 12/29] rtc.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- adjust identation of the titles;
- mark a table as such;
- don't capitalize chapter names.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/rtc.txt | 44 +++++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index ddc366026e00..47feb4414b7e 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -1,6 +1,6 @@
-
-	Real Time Clock (RTC) Drivers for Linux
-	=======================================
+=======================================
+Real Time Clock (RTC) Drivers for Linux
+=======================================
 
 When Linux developers talk about a "Real Time Clock", they usually mean
 something that tracks wall clock time and is battery backed so that it
@@ -32,8 +32,8 @@ only issue an alarm up to 24 hours in the future, other hardware may
 be able to schedule one any time in the upcoming century.
 
 
-	Old PC/AT-Compatible driver:  /dev/rtc
-	--------------------------------------
+Old PC/AT-Compatible driver:  /dev/rtc
+--------------------------------------
 
 All PCs (even Alpha machines) have a Real Time Clock built into them.
 Usually they are built into the chipset of the computer, but some may
@@ -105,8 +105,8 @@ that will be using this driver.  See the code at the end of this document.
 (The original /dev/rtc driver was written by Paul Gortmaker.)
 
 
-	New portable "RTC Class" drivers:  /dev/rtcN
-	--------------------------------------------
+New portable "RTC Class" drivers:  /dev/rtcN
+--------------------------------------------
 
 Because Linux supports many non-ACPI and non-PC platforms, some of which
 have more than one RTC style clock, it needed a more portable solution
@@ -136,35 +136,37 @@ a high functionality RTC is integrated into the SOC.  That system might read
 the system clock from the discrete RTC, but use the integrated one for all
 other tasks, because of its greater functionality.
 
-SYSFS INTERFACE
+SYSFS interface
 ---------------
 
 The sysfs interface under /sys/class/rtc/rtcN provides access to various
 rtc attributes without requiring the use of ioctls. All dates and times
 are in the RTC's timezone, rather than in system time.
 
-date:  	   	 RTC-provided date
-hctosys:   	 1 if the RTC provided the system time at boot via the
+================ ==============================================================
+date  	   	 RTC-provided date
+hctosys   	 1 if the RTC provided the system time at boot via the
 		 CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
-max_user_freq:	 The maximum interrupt rate an unprivileged user may request
+max_user_freq	 The maximum interrupt rate an unprivileged user may request
 		 from this RTC.
-name:		 The name of the RTC corresponding to this sysfs directory
-since_epoch:	 The number of seconds since the epoch according to the RTC
-time:		 RTC-provided time
-wakealarm:	 The time at which the clock will generate a system wakeup
+name		 The name of the RTC corresponding to this sysfs directory
+since_epoch	 The number of seconds since the epoch according to the RTC
+time		 RTC-provided time
+wakealarm	 The time at which the clock will generate a system wakeup
 		 event. This is a one shot wakeup event, so must be reset
-		 after wake if a daily wakeup is required. Format is seconds since
-		 the epoch by default, or if there's a leading +, seconds in the
-		 future, or if there is a leading +=, seconds ahead of the current
-		 alarm.
-offset:		 The amount which the rtc clock has been adjusted in firmware.
+		 after wake if a daily wakeup is required. Format is seconds
+		 since the epoch by default, or if there's a leading +, seconds
+		 in the future, or if there is a leading +=, seconds ahead of
+		 the current alarm.
+offset		 The amount which the rtc clock has been adjusted in firmware.
 		 Visible only if the driver supports clock offset adjustment.
 		 The unit is parts per billion, i.e. The number of clock ticks
 		 which are added to or removed from the rtc's base clock per
 		 billion ticks. A positive value makes a day pass more slowly,
 		 longer, and a negative value makes a day pass more quickly.
+================ ==============================================================
 
-IOCTL INTERFACE
+IOCTL interface
 ---------------
 
 The ioctl() calls supported by /dev/rtc are also supported by the RTC class
-- 
2.9.4

-- 
You received this message because you are subscribed to "rtc-linux".
Membership options at http://groups.google.com/group/rtc-linux .
Please read http://groups.google.com/group/rtc-linux/web/checklist
before submitting a driver.
--- 
You received this message because you are subscribed to the Google Groups "rtc-linux" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rtc-linux+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[PATCH 13/29] SAK.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- mark document title;
- use :Author: and :Date: for authorship;
- adjust notation for literals and bold;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/SAK.txt | 65 +++++++++++++++++++++++++++------------------------
 1 file changed, 34 insertions(+), 31 deletions(-)

diff --git a/Documentation/SAK.txt b/Documentation/SAK.txt
index 74be14679ed8..260e1d3687bd 100644
--- a/Documentation/SAK.txt
+++ b/Documentation/SAK.txt
@@ -1,5 +1,9 @@
-Linux 2.4.2 Secure Attention Key (SAK) handling
-18 March 2001, Andrew Morton
+=========================================
+Linux Secure Attention Key (SAK) handling
+=========================================
+
+:Date: 18 March 2001
+:Author: Andrew Morton
 
 An operating system's Secure Attention Key is a security tool which is
 provided as protection against trojan password capturing programs.  It
@@ -13,7 +17,7 @@ this sequence.  It is only available if the kernel was compiled with
 sysrq support.
 
 The proper way of generating a SAK is to define the key sequence using
-`loadkeys'.  This will work whether or not sysrq support is compiled
+``loadkeys``.  This will work whether or not sysrq support is compiled
 into the kernel.
 
 SAK works correctly when the keyboard is in raw mode.  This means that
@@ -25,64 +29,63 @@ What key sequence should you use? Well, CTRL-ALT-DEL is used to reboot
 the machine.  CTRL-ALT-BACKSPACE is magical to the X server.  We'll
 choose CTRL-ALT-PAUSE.
 
-In your rc.sysinit (or rc.local) file, add the command
+In your rc.sysinit (or rc.local) file, add the command::
 
 	echo "control alt keycode 101 = SAK" | /bin/loadkeys
 
 And that's it!  Only the superuser may reprogram the SAK key.
 
 
-NOTES
-=====
+.. note::
 
-1: Linux SAK is said to be not a "true SAK" as is required by
-   systems which implement C2 level security.  This author does not
-   know why.
+  1. Linux SAK is said to be not a "true SAK" as is required by
+     systems which implement C2 level security.  This author does not
+     know why.
 
 
-2: On the PC keyboard, SAK kills all applications which have
-   /dev/console opened.
+  2. On the PC keyboard, SAK kills all applications which have
+     /dev/console opened.
 
-   Unfortunately this includes a number of things which you don't
-   actually want killed.  This is because these applications are
-   incorrectly holding /dev/console open.  Be sure to complain to your
-   Linux distributor about this!
+     Unfortunately this includes a number of things which you don't
+     actually want killed.  This is because these applications are
+     incorrectly holding /dev/console open.  Be sure to complain to your
+     Linux distributor about this!
 
-   You can identify processes which will be killed by SAK with the
-   command
+     You can identify processes which will be killed by SAK with the
+     command::
 
 	# ls -l /proc/[0-9]*/fd/* | grep console
 	l-wx------    1 root     root           64 Mar 18 00:46 /proc/579/fd/0 -> /dev/console
 
-   Then:
+     Then::
 
 	# ps aux|grep 579
 	root       579  0.0  0.1  1088  436 ?        S    00:43   0:00 gpm -t ps/2
 
-   So `gpm' will be killed by SAK.  This is a bug in gpm.  It should
-   be closing standard input.  You can work around this by finding the
-   initscript which launches gpm and changing it thusly:
+     So ``gpm`` will be killed by SAK.  This is a bug in gpm.  It should
+     be closing standard input.  You can work around this by finding the
+     initscript which launches gpm and changing it thusly:
 
-   Old:
+     Old::
 
 	daemon gpm
 
-   New:
+     New::
 
 	daemon gpm < /dev/null
 
-   Vixie cron also seems to have this problem, and needs the same treatment.
+     Vixie cron also seems to have this problem, and needs the same treatment.
 
-   Also, one prominent Linux distribution has the following three
-   lines in its rc.sysinit and rc scripts:
+     Also, one prominent Linux distribution has the following three
+     lines in its rc.sysinit and rc scripts::
 
 	exec 3<&0
 	exec 4>&1
 	exec 5>&2
 
-   These commands cause *all* daemons which are launched by the
-   initscripts to have file descriptors 3, 4 and 5 attached to
-   /dev/console.  So SAK kills them all.  A workaround is to simply
-   delete these lines, but this may cause system management
-   applications to malfunction - test everything well.
+     These commands cause **all** daemons which are launched by the
+     initscripts to have file descriptors 3, 4 and 5 attached to
+     /dev/console.  So SAK kills them all.  A workaround is to simply
+     delete these lines, but this may cause system management
+     applications to malfunction - test everything well.
 
-- 
2.9.4

[PATCH 14/29] sgi-ioc4.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx.

In this case, just adding a title is enough.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/sgi-ioc4.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/sgi-ioc4.txt b/Documentation/sgi-ioc4.txt
index 876c96ae38db..72709222d3c0 100644
--- a/Documentation/sgi-ioc4.txt
+++ b/Documentation/sgi-ioc4.txt
@@ -1,3 +1,7 @@
+====================================
+SGI IOC4 PCI (multi function) device
+====================================
+
 The SGI IOC4 PCI device is a bit of a strange beast, so some notes on
 it are in order.
 
-- 
2.9.4

[PATCH 15/29] siphash.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Mark titles;
- Mark literal blocks;
- Use :Author: for authorship;
- Don't sumerate chapters;
- Adjust identation.

NOTE:

This file has actually two documents inside it, the first
one describing siphash, the second one describing halfsiphash.

It is likely a good idea to split them when it gets moved to
security/ (which is where it probably belongs).

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/siphash.txt | 186 +++++++++++++++++++++++++---------------------
 1 file changed, 100 insertions(+), 86 deletions(-)

diff --git a/Documentation/siphash.txt b/Documentation/siphash.txt
index 908d348ff777..9965821ab333 100644
--- a/Documentation/siphash.txt
+++ b/Documentation/siphash.txt
@@ -1,6 +1,8 @@
-         SipHash - a short input PRF
------------------------------------------------
-Written by Jason A. Donenfeld <jason@zx2c4.com>
+===========================
+SipHash - a short input PRF
+===========================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
 
 SipHash is a cryptographically secure PRF -- a keyed hash function -- that
 performs very well for short inputs, hence the name. It was designed by
@@ -13,58 +15,61 @@ an input buffer or several input integers. It spits out an integer that is
 indistinguishable from random. You may then use that integer as part of secure
 sequence numbers, secure cookies, or mask it off for use in a hash table.
 
-1. Generating a key
+Generating a key
+================
 
 Keys should always be generated from a cryptographically secure source of
-random numbers, either using get_random_bytes or get_random_once:
+random numbers, either using get_random_bytes or get_random_once::
 
-siphash_key_t key;
-get_random_bytes(&key, sizeof(key));
-
-If you're not deriving your key from here, you're doing it wrong.
-
-2. Using the functions
-
-There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer:
-
-u64 siphash(const void *data, size_t len, const siphash_key_t *key);
-
-And:
-
-u64 siphash_1u64(u64, const siphash_key_t *key);
-u64 siphash_2u64(u64, u64, const siphash_key_t *key);
-u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
-u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
-u64 siphash_1u32(u32, const siphash_key_t *key);
-u64 siphash_2u32(u32, u32, const siphash_key_t *key);
-u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
-u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
-
-If you pass the generic siphash function something of a constant length, it
-will constant fold at compile-time and automatically choose one of the
-optimized functions.
-
-3. Hashtable key function usage:
-
-struct some_hashtable {
-	DECLARE_HASHTABLE(hashtable, 8);
 	siphash_key_t key;
-};
+	get_random_bytes(&key, sizeof(key));
 
-void init_hashtable(struct some_hashtable *table)
-{
-	get_random_bytes(&table->key, sizeof(table->key));
-}
+If you're not deriving your key from here, you're doing it wrong.
 
-static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
-{
-	return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
-}
+Using the functions
+===================
+
+There are two variants of the function, one that takes a list of integers, and
+one that takes a buffer::
+
+	u64 siphash(const void *data, size_t len, const siphash_key_t *key);
+
+And::
+
+	u64 siphash_1u64(u64, const siphash_key_t *key);
+	u64 siphash_2u64(u64, u64, const siphash_key_t *key);
+	u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
+	u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
+	u64 siphash_1u32(u32, const siphash_key_t *key);
+	u64 siphash_2u32(u32, u32, const siphash_key_t *key);
+	u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
+	u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
+
+If you pass the generic siphash function something of a constant length, it
+will constant fold at compile-time and automatically choose one of the
+optimized functions.
+
+Hashtable key function usage::
+
+	struct some_hashtable {
+		DECLARE_HASHTABLE(hashtable, 8);
+		siphash_key_t key;
+	};
+
+	void init_hashtable(struct some_hashtable *table)
+	{
+		get_random_bytes(&table->key, sizeof(table->key));
+	}
+
+	static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+	{
+		return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+	}
 
 You may then iterate like usual over the returned hash bucket.
 
-4. Security
+Security
+========
 
 SipHash has a very high security margin, with its 128-bit key. So long as the
 key is kept secret, it is impossible for an attacker to guess the outputs of
@@ -73,7 +78,8 @@ is significant.
 
 Linux implements the "2-4" variant of SipHash.
 
-5. Struct-passing Pitfalls
+Struct-passing Pitfalls
+=======================
 
 Often times the XuY functions will not be large enough, and instead you'll
 want to pass a pre-filled struct to siphash. When doing this, it's important
@@ -81,30 +87,32 @@ to always ensure the struct has no padding holes. The easiest way to do this
 is to simply arrange the members of the struct in descending order of size,
 and to use offsetendof() instead of sizeof() for getting the size. For
 performance reasons, if possible, it's probably a good thing to align the
-struct to the right boundary. Here's an example:
+struct to the right boundary. Here's an example::
 
-const struct {
-	struct in6_addr saddr;
-	u32 counter;
-	u16 dport;
-} __aligned(SIPHASH_ALIGNMENT) combined = {
-	.saddr = *(struct in6_addr *)saddr,
-	.counter = counter,
-	.dport = dport
-};
-u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
+	const struct {
+		struct in6_addr saddr;
+		u32 counter;
+		u16 dport;
+	} __aligned(SIPHASH_ALIGNMENT) combined = {
+		.saddr = *(struct in6_addr *)saddr,
+		.counter = counter,
+		.dport = dport
+	};
+	u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
 
-6. Resources
+Resources
+=========
 
 Read the SipHash paper if you're interested in learning more:
 https://131002.net/siphash/siphash.pdf
 
+-------------------------------------------------------------------------------
 
-~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~
-
+===============================================
 HalfSipHash - SipHash's insecure younger cousin
------------------------------------------------
-Written by Jason A. Donenfeld <jason@zx2c4.com>
+===============================================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
 
 On the off-chance that SipHash is not fast enough for your needs, you might be
 able to justify using HalfSipHash, a terrifying but potentially useful
@@ -120,7 +128,8 @@ then when you can be absolutely certain that the outputs will never be
 transmitted out of the kernel. This is only remotely useful over `jhash` as a
 means of mitigating hashtable flooding denial of service attacks.
 
-1. Generating a key
+Generating a key
+================
 
 Keys should always be generated from a cryptographically secure source of
 random numbers, either using get_random_bytes or get_random_once:
@@ -130,44 +139,49 @@ get_random_bytes(&key, sizeof(key));
 
 If you're not deriving your key from here, you're doing it wrong.
 
-2. Using the functions
+Using the functions
+===================
 
 There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer:
+one that takes a buffer::
 
-u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
+	u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
 
-And:
+And::
 
-u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
-u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
-u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
-u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
+	u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
+	u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
+	u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
+	u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
 
 If you pass the generic hsiphash function something of a constant length, it
 will constant fold at compile-time and automatically choose one of the
 optimized functions.
 
-3. Hashtable key function usage:
+Hashtable key function usage
+============================
 
-struct some_hashtable {
-	DECLARE_HASHTABLE(hashtable, 8);
-	hsiphash_key_t key;
-};
+::
 
-void init_hashtable(struct some_hashtable *table)
-{
-	get_random_bytes(&table->key, sizeof(table->key));
-}
+	struct some_hashtable {
+		DECLARE_HASHTABLE(hashtable, 8);
+		hsiphash_key_t key;
+	};
 
-static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
-{
-	return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
-}
+	void init_hashtable(struct some_hashtable *table)
+	{
+		get_random_bytes(&table->key, sizeof(table->key));
+	}
+
+	static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+	{
+		return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+	}
 
 You may then iterate like usual over the returned hash bucket.
 
-4. Performance
+Performance
+===========
 
 HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
 this will not be a problem, as the hashtable lookup isn't the bottleneck. And
-- 
2.9.4

[PATCH 16/29] SM501.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- adjust document title;
- use the copyright markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/SM501.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/SM501.txt b/Documentation/SM501.txt
index 561826f82093..882507453ba4 100644
--- a/Documentation/SM501.txt
+++ b/Documentation/SM501.txt
@@ -1,7 +1,10 @@
-			SM501 Driver
-			============
+.. include:: <isonum.txt>
 
-Copyright 2006, 2007 Simtec Electronics
+============
+SM501 Driver
+============
+
+:Copyright: |copy| 2006, 2007 Simtec Electronics
 
 The Silicon Motion SM501 multimedia companion chip is a multifunction device
 which may provide numerous interfaces including USB host controller USB gadget,
-- 
2.9.4

[PATCH 17/29] smsc_ece1099.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Add a title for the document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/smsc_ece1099.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/smsc_ece1099.txt b/Documentation/smsc_ece1099.txt
index 6b492e82b43d..079277421eaf 100644
--- a/Documentation/smsc_ece1099.txt
+++ b/Documentation/smsc_ece1099.txt
@@ -1,3 +1,7 @@
+=================================================
+Msc Keyboard Scan Expansion/GPIO Expansion device
+=================================================
+
 What is smsc-ece1099?
 ----------------------
 
-- 
2.9.4

[PATCH 18/29] static-keys.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark titles;
- Add a warning mark;
- Mark literals and literal blocks;
- Adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/static-keys.txt | 199 ++++++++++++++++++++++--------------------
 1 file changed, 104 insertions(+), 95 deletions(-)

diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt
index ef419fd0897f..b83dfa1c0602 100644
--- a/Documentation/static-keys.txt
+++ b/Documentation/static-keys.txt
@@ -1,30 +1,34 @@
-			Static Keys
-			-----------
+===========
+Static Keys
+===========
 
-DEPRECATED API:
+.. warning::
 
-The use of 'struct static_key' directly, is now DEPRECATED. In addition
-static_key_{true,false}() is also DEPRECATED. IE DO NOT use the following:
+   DEPRECATED API:
 
-struct static_key false = STATIC_KEY_INIT_FALSE;
-struct static_key true = STATIC_KEY_INIT_TRUE;
-static_key_true()
-static_key_false()
+   The use of 'struct static_key' directly, is now DEPRECATED. In addition
+   static_key_{true,false}() is also DEPRECATED. IE DO NOT use the following::
 
-The updated API replacements are:
+	struct static_key false = STATIC_KEY_INIT_FALSE;
+	struct static_key true = STATIC_KEY_INIT_TRUE;
+	static_key_true()
+	static_key_false()
 
-DEFINE_STATIC_KEY_TRUE(key);
-DEFINE_STATIC_KEY_FALSE(key);
-DEFINE_STATIC_KEY_ARRAY_TRUE(keys, count);
-DEFINE_STATIC_KEY_ARRAY_FALSE(keys, count);
-static_branch_likely()
-static_branch_unlikely()
+   The updated API replacements are::
 
-0) Abstract
+	DEFINE_STATIC_KEY_TRUE(key);
+	DEFINE_STATIC_KEY_FALSE(key);
+	DEFINE_STATIC_KEY_ARRAY_TRUE(keys, count);
+	DEFINE_STATIC_KEY_ARRAY_FALSE(keys, count);
+	static_branch_likely()
+	static_branch_unlikely()
+
+Abstract
+========
 
 Static keys allows the inclusion of seldom used features in
 performance-sensitive fast-path kernel code, via a GCC feature and a code
-patching technique. A quick example:
+patching technique. A quick example::
 
 	DEFINE_STATIC_KEY_FALSE(key);
 
@@ -45,7 +49,8 @@ The static_branch_unlikely() branch will be generated into the code with as litt
 impact to the likely code path as possible.
 
 
-1) Motivation
+Motivation
+==========
 
 
 Currently, tracepoints are implemented using a conditional branch. The
@@ -60,7 +65,8 @@ possible. Although tracepoints are the original motivation for this work, other
 kernel code paths should be able to make use of the static keys facility.
 
 
-2) Solution
+Solution
+========
 
 
 gcc (v4.5) adds a new 'asm goto' statement that allows branching to a label:
@@ -71,7 +77,7 @@ Using the 'asm goto', we can create branches that are either taken or not taken
 by default, without the need to check memory. Then, at run-time, we can patch
 the branch site to change the branch direction.
 
-For example, if we have a simple branch that is disabled by default:
+For example, if we have a simple branch that is disabled by default::
 
 	if (static_branch_unlikely(&key))
 		printk("I am the true branch\n");
@@ -87,14 +93,15 @@ optimization.
 This lowlevel patching mechanism is called 'jump label patching', and it gives
 the basis for the static keys facility.
 
-3) Static key label API, usage and examples:
+Static key label API, usage and examples
+========================================
 
 
-In order to make use of this optimization you must first define a key:
+In order to make use of this optimization you must first define a key::
 
 	DEFINE_STATIC_KEY_TRUE(key);
 
-or:
+or::
 
 	DEFINE_STATIC_KEY_FALSE(key);
 
@@ -102,14 +109,14 @@ or:
 The key must be global, that is, it can't be allocated on the stack or dynamically
 allocated at run-time.
 
-The key is then used in code as:
+The key is then used in code as::
 
         if (static_branch_unlikely(&key))
                 do unlikely code
         else
                 do likely code
 
-Or:
+Or::
 
         if (static_branch_likely(&key))
                 do likely code
@@ -120,15 +127,15 @@ Keys defined via DEFINE_STATIC_KEY_TRUE(), or DEFINE_STATIC_KEY_FALSE, may
 be used in either static_branch_likely() or static_branch_unlikely()
 statements.
 
-Branch(es) can be set true via:
+Branch(es) can be set true via::
 
-static_branch_enable(&key);
+	static_branch_enable(&key);
 
-or false via:
+or false via::
 
-static_branch_disable(&key);
+	static_branch_disable(&key);
 
-The branch(es) can then be switched via reference counts:
+The branch(es) can then be switched via reference counts::
 
 	static_branch_inc(&key);
 	...
@@ -142,11 +149,11 @@ static_branch_inc(), will change the branch back to true. Likewise, if the
 key is initialized false, a 'static_branch_inc()', will change the branch to
 true. And then a 'static_branch_dec()', will again make the branch false.
 
-Where an array of keys is required, it can be defined as:
+Where an array of keys is required, it can be defined as::
 
 	DEFINE_STATIC_KEY_ARRAY_TRUE(keys, count);
 
-or:
+or::
 
 	DEFINE_STATIC_KEY_ARRAY_FALSE(keys, count);
 
@@ -159,96 +166,98 @@ simply fall back to a traditional, load, test, and jump sequence. Also, the
 struct jump_entry table must be at least 4-byte aligned because the
 static_key->entry field makes use of the two least significant bits.
 
-* select HAVE_ARCH_JUMP_LABEL, see: arch/x86/Kconfig
+* ``select HAVE_ARCH_JUMP_LABEL``,
+    see: arch/x86/Kconfig
 
-* #define JUMP_LABEL_NOP_SIZE, see: arch/x86/include/asm/jump_label.h
+* ``#define JUMP_LABEL_NOP_SIZE``,
+    see: arch/x86/include/asm/jump_label.h
 
-* __always_inline bool arch_static_branch(struct static_key *key, bool branch), see:
-					arch/x86/include/asm/jump_label.h
+* ``__always_inline bool arch_static_branch(struct static_key *key, bool branch)``,
+    see: arch/x86/include/asm/jump_label.h
 
-* __always_inline bool arch_static_branch_jump(struct static_key *key, bool branch),
-					see: arch/x86/include/asm/jump_label.h
+* ``__always_inline bool arch_static_branch_jump(struct static_key *key, bool branch)``,
+    see: arch/x86/include/asm/jump_label.h
 
-* void arch_jump_label_transform(struct jump_entry *entry, enum jump_label_type type),
-					see: arch/x86/kernel/jump_label.c
+* ``void arch_jump_label_transform(struct jump_entry *entry, enum jump_label_type type)``,
+    see: arch/x86/kernel/jump_label.c
 
-* __init_or_module void arch_jump_label_transform_static(struct jump_entry *entry, enum jump_label_type type),
-					see: arch/x86/kernel/jump_label.c
+* ``__init_or_module void arch_jump_label_transform_static(struct jump_entry *entry, enum jump_label_type type)``,
+    see: arch/x86/kernel/jump_label.c
 
-
-* struct jump_entry, see: arch/x86/include/asm/jump_label.h
+* ``struct jump_entry``,
+    see: arch/x86/include/asm/jump_label.h
 
 
 5) Static keys / jump label analysis, results (x86_64):
 
 
 As an example, let's add the following branch to 'getppid()', such that the
-system call now looks like:
+system call now looks like::
 
-SYSCALL_DEFINE0(getppid)
-{
+  SYSCALL_DEFINE0(getppid)
+  {
         int pid;
 
-+       if (static_branch_unlikely(&key))
-+               printk("I am the true branch\n");
+  +     if (static_branch_unlikely(&key))
+  +             printk("I am the true branch\n");
 
         rcu_read_lock();
         pid = task_tgid_vnr(rcu_dereference(current->real_parent));
         rcu_read_unlock();
 
         return pid;
-}
+  }
 
-The resulting instructions with jump labels generated by GCC is:
+The resulting instructions with jump labels generated by GCC is::
 
-ffffffff81044290 <sys_getppid>:
-ffffffff81044290:       55                      push   %rbp
-ffffffff81044291:       48 89 e5                mov    %rsp,%rbp
-ffffffff81044294:       e9 00 00 00 00          jmpq   ffffffff81044299 <sys_getppid+0x9>
-ffffffff81044299:       65 48 8b 04 25 c0 b6    mov    %gs:0xb6c0,%rax
-ffffffff810442a0:       00 00
-ffffffff810442a2:       48 8b 80 80 02 00 00    mov    0x280(%rax),%rax
-ffffffff810442a9:       48 8b 80 b0 02 00 00    mov    0x2b0(%rax),%rax
-ffffffff810442b0:       48 8b b8 e8 02 00 00    mov    0x2e8(%rax),%rdi
-ffffffff810442b7:       e8 f4 d9 00 00          callq  ffffffff81051cb0 <pid_vnr>
-ffffffff810442bc:       5d                      pop    %rbp
-ffffffff810442bd:       48 98                   cltq
-ffffffff810442bf:       c3                      retq
-ffffffff810442c0:       48 c7 c7 e3 54 98 81    mov    $0xffffffff819854e3,%rdi
-ffffffff810442c7:       31 c0                   xor    %eax,%eax
-ffffffff810442c9:       e8 71 13 6d 00          callq  ffffffff8171563f <printk>
-ffffffff810442ce:       eb c9                   jmp    ffffffff81044299 <sys_getppid+0x9>
+  ffffffff81044290 <sys_getppid>:
+  ffffffff81044290:       55                      push   %rbp
+  ffffffff81044291:       48 89 e5                mov    %rsp,%rbp
+  ffffffff81044294:       e9 00 00 00 00          jmpq   ffffffff81044299 <sys_getppid+0x9>
+  ffffffff81044299:       65 48 8b 04 25 c0 b6    mov    %gs:0xb6c0,%rax
+  ffffffff810442a0:       00 00
+  ffffffff810442a2:       48 8b 80 80 02 00 00    mov    0x280(%rax),%rax
+  ffffffff810442a9:       48 8b 80 b0 02 00 00    mov    0x2b0(%rax),%rax
+  ffffffff810442b0:       48 8b b8 e8 02 00 00    mov    0x2e8(%rax),%rdi
+  ffffffff810442b7:       e8 f4 d9 00 00          callq  ffffffff81051cb0 <pid_vnr>
+  ffffffff810442bc:       5d                      pop    %rbp
+  ffffffff810442bd:       48 98                   cltq
+  ffffffff810442bf:       c3                      retq
+  ffffffff810442c0:       48 c7 c7 e3 54 98 81    mov    $0xffffffff819854e3,%rdi
+  ffffffff810442c7:       31 c0                   xor    %eax,%eax
+  ffffffff810442c9:       e8 71 13 6d 00          callq  ffffffff8171563f <printk>
+  ffffffff810442ce:       eb c9                   jmp    ffffffff81044299 <sys_getppid+0x9>
 
-Without the jump label optimization it looks like:
+Without the jump label optimization it looks like::
 
-ffffffff810441f0 <sys_getppid>:
-ffffffff810441f0:       8b 05 8a 52 d8 00       mov    0xd8528a(%rip),%eax        # ffffffff81dc9480 <key>
-ffffffff810441f6:       55                      push   %rbp
-ffffffff810441f7:       48 89 e5                mov    %rsp,%rbp
-ffffffff810441fa:       85 c0                   test   %eax,%eax
-ffffffff810441fc:       75 27                   jne    ffffffff81044225 <sys_getppid+0x35>
-ffffffff810441fe:       65 48 8b 04 25 c0 b6    mov    %gs:0xb6c0,%rax
-ffffffff81044205:       00 00
-ffffffff81044207:       48 8b 80 80 02 00 00    mov    0x280(%rax),%rax
-ffffffff8104420e:       48 8b 80 b0 02 00 00    mov    0x2b0(%rax),%rax
-ffffffff81044215:       48 8b b8 e8 02 00 00    mov    0x2e8(%rax),%rdi
-ffffffff8104421c:       e8 2f da 00 00          callq  ffffffff81051c50 <pid_vnr>
-ffffffff81044221:       5d                      pop    %rbp
-ffffffff81044222:       48 98                   cltq
-ffffffff81044224:       c3                      retq
-ffffffff81044225:       48 c7 c7 13 53 98 81    mov    $0xffffffff81985313,%rdi
-ffffffff8104422c:       31 c0                   xor    %eax,%eax
-ffffffff8104422e:       e8 60 0f 6d 00          callq  ffffffff81715193 <printk>
-ffffffff81044233:       eb c9                   jmp    ffffffff810441fe <sys_getppid+0xe>
-ffffffff81044235:       66 66 2e 0f 1f 84 00    data32 nopw %cs:0x0(%rax,%rax,1)
-ffffffff8104423c:       00 00 00 00
+  ffffffff810441f0 <sys_getppid>:
+  ffffffff810441f0:       8b 05 8a 52 d8 00       mov    0xd8528a(%rip),%eax        # ffffffff81dc9480 <key>
+  ffffffff810441f6:       55                      push   %rbp
+  ffffffff810441f7:       48 89 e5                mov    %rsp,%rbp
+  ffffffff810441fa:       85 c0                   test   %eax,%eax
+  ffffffff810441fc:       75 27                   jne    ffffffff81044225 <sys_getppid+0x35>
+  ffffffff810441fe:       65 48 8b 04 25 c0 b6    mov    %gs:0xb6c0,%rax
+  ffffffff81044205:       00 00
+  ffffffff81044207:       48 8b 80 80 02 00 00    mov    0x280(%rax),%rax
+  ffffffff8104420e:       48 8b 80 b0 02 00 00    mov    0x2b0(%rax),%rax
+  ffffffff81044215:       48 8b b8 e8 02 00 00    mov    0x2e8(%rax),%rdi
+  ffffffff8104421c:       e8 2f da 00 00          callq  ffffffff81051c50 <pid_vnr>
+  ffffffff81044221:       5d                      pop    %rbp
+  ffffffff81044222:       48 98                   cltq
+  ffffffff81044224:       c3                      retq
+  ffffffff81044225:       48 c7 c7 13 53 98 81    mov    $0xffffffff81985313,%rdi
+  ffffffff8104422c:       31 c0                   xor    %eax,%eax
+  ffffffff8104422e:       e8 60 0f 6d 00          callq  ffffffff81715193 <printk>
+  ffffffff81044233:       eb c9                   jmp    ffffffff810441fe <sys_getppid+0xe>
+  ffffffff81044235:       66 66 2e 0f 1f 84 00    data32 nopw %cs:0x0(%rax,%rax,1)
+  ffffffff8104423c:       00 00 00 00
 
 Thus, the disable jump label case adds a 'mov', 'test' and 'jne' instruction
 vs. the jump label case just has a 'no-op' or 'jmp 0'. (The jmp 0, is patched
 to a 5 byte atomic no-op instruction at boot-time.) Thus, the disabled jump
-label case adds:
+label case adds::
 
-6 (mov) + 2 (test) + 2 (jne) = 10 - 5 (5 byte jump 0) = 5 addition bytes.
+  6 (mov) + 2 (test) + 2 (jne) = 10 - 5 (5 byte jump 0) = 5 addition bytes.
 
 If we then include the padding bytes, the jump label code saves, 16 total bytes
 of instruction memory for this small function. In this case the non-jump label
@@ -262,7 +271,7 @@ Since there are a number of static key API uses in the scheduler paths,
 'pipe-test' (also known as 'perf bench sched pipe') can be used to show the
 performance improvement. Testing done on 3.3.0-rc2:
 
-jump label disabled:
+jump label disabled::
 
  Performance counter stats for 'bash -c /tmp/pipe-test' (50 runs):
 
@@ -279,7 +288,7 @@ jump label disabled:
 
        1.601607384 seconds time elapsed                                          ( +-  0.07% )
 
-jump label enabled:
+jump label enabled::
 
  Performance counter stats for 'bash -c /tmp/pipe-test' (50 runs):
 
-- 
2.9.4

[PATCH 19/29] svga.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use standard notation for titles;
- Use the note mark;
- mark literal blocks;
- adjust identation;
- mark the table.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/svga.txt | 146 +++++++++++++++++++++++++++----------------------
 1 file changed, 80 insertions(+), 66 deletions(-)

diff --git a/Documentation/svga.txt b/Documentation/svga.txt
index cd66ec836e4f..119f1515b1ac 100644
--- a/Documentation/svga.txt
+++ b/Documentation/svga.txt
@@ -1,24 +1,31 @@
-		       Video Mode Selection Support 2.13
-		    (c) 1995--1999 Martin Mares, <mj@ucw.cz>
---------------------------------------------------------------------------------
+.. include:: <isonum.txt>
 
-1. Intro
-~~~~~~~~
-   This small document describes the "Video Mode Selection" feature which
+=================================
+Video Mode Selection Support 2.13
+=================================
+
+:Copyright: |copy| 1995--1999 Martin Mares, <mj@ucw.cz>
+
+Intro
+~~~~~
+
+This small document describes the "Video Mode Selection" feature which
 allows the use of various special video modes supported by the video BIOS. Due
 to usage of the BIOS, the selection is limited to boot time (before the
 kernel decompression starts) and works only on 80X86 machines.
 
-   **  Short intro for the impatient: Just use vga=ask for the first time,
-   **  enter `scan' on the video mode prompt, pick the mode you want to use,
-   **  remember its mode ID (the four-digit hexadecimal number) and then
-   **  set the vga parameter to this number (converted to decimal first).
+.. note::
 
-   The video mode to be used is selected by a kernel parameter which can be
+   Short intro for the impatient: Just use vga=ask for the first time,
+   enter ``scan`` on the video mode prompt, pick the mode you want to use,
+   remember its mode ID (the four-digit hexadecimal number) and then
+   set the vga parameter to this number (converted to decimal first).
+
+The video mode to be used is selected by a kernel parameter which can be
 specified in the kernel Makefile (the SVGA_MODE=... line) or by the "vga=..."
 option of LILO (or some other boot loader you use) or by the "vidmode" utility
 (present in standard Linux utility packages). You can use the following values
-of this parameter:
+of this parameter::
 
    NORMAL_VGA - Standard 80x25 mode available on all display adapters.
 
@@ -37,77 +44,79 @@ of this parameter:
       for exact meaning of the ID). Warning: rdev and LILO don't support
       hexadecimal numbers -- you have to convert it to decimal manually.
 
-2. Menu
-~~~~~~~
-   The ASK_VGA mode causes the kernel to offer a video mode menu upon
+Menu
+~~~~
+
+The ASK_VGA mode causes the kernel to offer a video mode menu upon
 bootup. It displays a "Press <RETURN> to see video modes available, <SPACE>
 to continue or wait 30 secs" message. If you press <RETURN>, you enter the
 menu, if you press <SPACE> or wait 30 seconds, the kernel will boot up in
 the standard 80x25 mode.
 
-   The menu looks like:
+The menu looks like::
 
-Video adapter: <name-of-detected-video-adapter>
-Mode:    COLSxROWS:
-0  0F00  80x25
-1  0F01  80x50
-2  0F02  80x43
-3  0F03  80x26
-....
-Enter mode number or `scan': <flashing-cursor-here>
+	Video adapter: <name-of-detected-video-adapter>
+	Mode:    COLSxROWS:
+	0  0F00  80x25
+	1  0F01  80x50
+	2  0F02  80x43
+	3  0F03  80x26
+	....
+	Enter mode number or ``scan``: <flashing-cursor-here>
 
-   <name-of-detected-video-adapter> tells what video adapter did Linux detect
+<name-of-detected-video-adapter> tells what video adapter did Linux detect
 -- it's either a generic adapter name (MDA, CGA, HGC, EGA, VGA, VESA VGA [a VGA
 with VESA-compliant BIOS]) or a chipset name (e.g., Trident). Direct detection
 of chipsets is turned off by default (see CONFIG_VIDEO_SVGA in chapter 4 to see
 how to enable it if you really want) as it's inherently unreliable due to
 absolutely insane PC design.
 
-   "0  0F00  80x25" means that the first menu item (the menu items are numbered
+"0  0F00  80x25" means that the first menu item (the menu items are numbered
 from "0" to "9" and from "a" to "z") is a 80x25 mode with ID=0x0f00 (see the
 next section for a description of mode IDs).
 
-   <flashing-cursor-here> encourages you to enter the item number or mode ID
+<flashing-cursor-here> encourages you to enter the item number or mode ID
 you wish to set and press <RETURN>. If the computer complains something about
 "Unknown mode ID", it is trying to tell you that it isn't possible to set such
 a mode. It's also possible to press only <RETURN> which leaves the current mode.
 
-   The mode list usually contains a few basic modes and some VESA modes.  In
+The mode list usually contains a few basic modes and some VESA modes.  In
 case your chipset has been detected, some chipset-specific modes are shown as
 well (some of these might be missing or unusable on your machine as different
 BIOSes are often shipped with the same card and the mode numbers depend purely
 on the VGA BIOS).
 
-   The modes displayed on the menu are partially sorted: The list starts with
+The modes displayed on the menu are partially sorted: The list starts with
 the standard modes (80x25 and 80x50) followed by "special" modes (80x28 and
 80x43), local modes (if the local modes feature is enabled), VESA modes and
 finally SVGA modes for the auto-detected adapter.
 
-   If you are not happy with the mode list offered (e.g., if you think your card
+If you are not happy with the mode list offered (e.g., if you think your card
 is able to do more), you can enter "scan" instead of item number / mode ID.  The
 program will try to ask the BIOS for all possible video mode numbers and test
 what happens then. The screen will be probably flashing wildly for some time and
 strange noises will be heard from inside the monitor and so on and then, really
 all consistent video modes supported by your BIOS will appear (plus maybe some
-`ghost modes'). If you are afraid this could damage your monitor, don't use this
-function.
+``ghost modes``). If you are afraid this could damage your monitor, don't use
+this function.
 
-   After scanning, the mode ordering is a bit different: the auto-detected SVGA
-modes are not listed at all and the modes revealed by `scan' are shown before
+After scanning, the mode ordering is a bit different: the auto-detected SVGA
+modes are not listed at all and the modes revealed by ``scan`` are shown before
 all VESA modes.
 
-3. Mode IDs
-~~~~~~~~~~~
-   Because of the complexity of all the video stuff, the video mode IDs
+Mode IDs
+~~~~~~~~
+
+Because of the complexity of all the video stuff, the video mode IDs
 used here are also a bit complex. A video mode ID is a 16-bit number usually
 expressed in a hexadecimal notation (starting with "0x"). You can set a mode
 by entering its mode directly if you know it even if it isn't shown on the menu.
 
-The ID numbers can be divided to three regions:
+The ID numbers can be divided to those regions::
 
    0x0000 to 0x00ff - menu item references. 0x0000 is the first item. Don't use
 	outside the menu as this can change from boot to boot (especially if you
-	have used the `scan' feature).
+	have used the ``scan`` feature).
 
    0x0100 to 0x017f - standard BIOS modes. The ID is a BIOS video mode number
 	(as presented to INT 10, function 00) increased by 0x0100.
@@ -142,53 +151,54 @@ The ID numbers can be divided to three regions:
 	0xffff	equivalent to 0x0f00 (standard 80x25)
 	0xfffe	equivalent to 0x0f01 (EGA 80x43 or VGA 80x50)
 
-   If you add 0x8000 to the mode ID, the program will try to recalculate
+If you add 0x8000 to the mode ID, the program will try to recalculate
 vertical display timing according to mode parameters, which can be used to
 eliminate some annoying bugs of certain VGA BIOSes (usually those used for
 cards with S3 chipsets and old Cirrus Logic BIOSes) -- mainly extra lines at the
 end of the display.
 
-4. Options
-~~~~~~~~~~
-   Some options can be set in the source text (in arch/i386/boot/video.S).
+Options
+~~~~~~~
+
+Some options can be set in the source text (in arch/i386/boot/video.S).
 All of them are simple #define's -- change them to #undef's when you want to
 switch them off. Currently supported:
 
-   CONFIG_VIDEO_SVGA - enables autodetection of SVGA cards. This is switched
+CONFIG_VIDEO_SVGA - enables autodetection of SVGA cards. This is switched
 off by default as it's a bit unreliable due to terribly bad PC design. If you
-really want to have the adapter autodetected (maybe in case the `scan' feature
+really want to have the adapter autodetected (maybe in case the ``scan`` feature
 doesn't work on your machine), switch this on and don't cry if the results
 are not completely sane. In case you really need this feature, please drop me
 a mail as I think of removing it some day.
 
-   CONFIG_VIDEO_VESA - enables autodetection of VESA modes. If it doesn't work
+CONFIG_VIDEO_VESA - enables autodetection of VESA modes. If it doesn't work
 on your machine (or displays a "Error: Scanning of VESA modes failed" message),
 you can switch it off and report as a bug.
 
-   CONFIG_VIDEO_COMPACT - enables compacting of the video mode list. If there
+CONFIG_VIDEO_COMPACT - enables compacting of the video mode list. If there
 are more modes with the same screen size, only the first one is kept (see above
 for more info on mode ordering). However, in very strange cases it's possible
 that the first "version" of the mode doesn't work although some of the others
 do -- in this case turn this switch off to see the rest.
 
-   CONFIG_VIDEO_RETAIN - enables retaining of screen contents when switching
+CONFIG_VIDEO_RETAIN - enables retaining of screen contents when switching
 video modes. Works only with some boot loaders which leave enough room for the
 buffer. (If you have old LILO, you can adjust heap_end_ptr and loadflags
 in setup.S, but it's better to upgrade the boot loader...)
 
-   CONFIG_VIDEO_LOCAL - enables inclusion of "local modes" in the list. The
+CONFIG_VIDEO_LOCAL - enables inclusion of "local modes" in the list. The
 local modes are added automatically to the beginning of the list not depending
 on hardware configuration. The local modes are listed in the source text after
 the "local_mode_table:" line. The comment before this line describes the format
 of the table (which also includes a video card name to be displayed on the
 top of the menu).
 
-   CONFIG_VIDEO_400_HACK - force setting of 400 scan lines for standard VGA
+CONFIG_VIDEO_400_HACK - force setting of 400 scan lines for standard VGA
 modes. This option is intended to be used on certain buggy BIOSes which draw
 some useless logo using font download and then fail to reset the correct mode.
 Don't use unless needed as it forces resetting the video card.
 
-   CONFIG_VIDEO_GFX_HACK - includes special hack for setting of graphics modes
+CONFIG_VIDEO_GFX_HACK - includes special hack for setting of graphics modes
 to be used later by special drivers (e.g., 800x600 on IBM ThinkPad -- see
 ftp://ftp.phys.keio.ac.jp/pub/XFree86/800x600/XF86Configs/XF86Config.IBM_TP560).
 Allows to set _any_ BIOS mode including graphic ones and forcing specific
@@ -196,33 +206,36 @@ text screen resolution instead of peeking it from BIOS variables. Don't use
 unless you think you know what you're doing. To activate this setup, use
 mode number 0x0f08 (see section 3).
 
-5. Still doesn't work?
-~~~~~~~~~~~~~~~~~~~~~~
-   When the mode detection doesn't work (e.g., the mode list is incorrect or
+Still doesn't work?
+~~~~~~~~~~~~~~~~~~~
+
+When the mode detection doesn't work (e.g., the mode list is incorrect or
 the machine hangs instead of displaying the menu), try to switch off some of
 the configuration options listed in section 4. If it fails, you can still use
 your kernel with the video mode set directly via the kernel parameter.
 
-   In either case, please send me a bug report containing what _exactly_
+In either case, please send me a bug report containing what _exactly_
 happens and how do the configuration switches affect the behaviour of the bug.
 
-   If you start Linux from M$-DOS, you might also use some DOS tools for
+If you start Linux from M$-DOS, you might also use some DOS tools for
 video mode setting. In this case, you must specify the 0x0f04 mode ("leave
 current settings") to Linux, because if you don't and you use any non-standard
 mode, Linux will switch to 80x25 automatically.
 
-   If you set some extended mode and there's one or more extra lines on the
+If you set some extended mode and there's one or more extra lines on the
 bottom of the display containing already scrolled-out text, your VGA BIOS
 contains the most common video BIOS bug called "incorrect vertical display
 end setting". Adding 0x8000 to the mode ID might fix the problem. Unfortunately,
 this must be done manually -- no autodetection mechanisms are available.
 
-   If you have a VGA card and your display still looks as on EGA, your BIOS
+If you have a VGA card and your display still looks as on EGA, your BIOS
 is probably broken and you need to set the CONFIG_VIDEO_400_HACK switch to
 force setting of the correct mode.
 
-6. History
-~~~~~~~~~~
+History
+~~~~~~~
+
+=============== ================================================================
 1.0 (??-Nov-95)	First version supporting all adapters supported by the old
 		setup.S + Cirrus Logic 54XX. Present in some 1.3.4? kernels
 		and then removed due to instability on some machines.
@@ -260,17 +273,18 @@ force setting of the correct mode.
 		  original version written by hhanemaa@cs.ruu.nl, patched by
 		  Jeff Chua, rewritten by me).
 		- Screen store/restore fixed.
-2.8 (14-Apr-96)	- Previous release was not compilable without CONFIG_VIDEO_SVGA.
+2.8 (14-Apr-96) - Previous release was not compilable without CONFIG_VIDEO_SVGA.
 		- Better recognition of text modes during mode scan.
 2.9 (12-May-96)	- Ignored VESA modes 0x80 - 0xff (more VESA BIOS bugs!)
-2.10 (11-Nov-96)- The whole thing made optional.
+2.10(11-Nov-96) - The whole thing made optional.
 		- Added the CONFIG_VIDEO_400_HACK switch.
 		- Added the CONFIG_VIDEO_GFX_HACK switch.
 		- Code cleanup.
-2.11 (03-May-97)- Yet another cleanup, now including also the documentation.
-		- Direct testing of SVGA adapters turned off by default, `scan'
+2.11(03-May-97) - Yet another cleanup, now including also the documentation.
+		- Direct testing of SVGA adapters turned off by default, ``scan``
 		  offered explicitly on the prompt line.
 		- Removed the doc section describing adding of new probing
 		  functions as I try to get rid of _all_ hardware probing here.
-2.12 (25-May-98)- Added support for VESA frame buffer graphics.
-2.13 (14-May-99)- Minor documentation fixes.
+2.12(25-May-98) Added support for VESA frame buffer graphics.
+2.13(14-May-99) Minor documentation fixes.
+=============== ================================================================
-- 
2.9.4

[PATCH 20/29] sync_file.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use markup for document title and authorship;
- Mark literal blocks;
- Use a numbered list for references.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/sync_file.txt | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt
index c3d033a06e8d..496fb2c3b3e6 100644
--- a/Documentation/sync_file.txt
+++ b/Documentation/sync_file.txt
@@ -1,8 +1,8 @@
-			      Sync File API Guide
-			      ~~~~~~~~~~~~~~~~~~~
+===================
+Sync File API Guide
+===================
 
-				Gustavo Padovan
-			  <gustavo at padovan dot org>
+:Author: Gustavo Padovan <gustavo at padovan dot org>
 
 This document serves as a guide for device drivers writers on what the
 sync_file API is, and how drivers can support it. Sync file is the carrier of
@@ -46,16 +46,17 @@ Creating Sync Files
 
 When a driver needs to send an out-fence userspace it creates a sync_file.
 
-Interface:
+Interface::
+
 	struct sync_file *sync_file_create(struct dma_fence *fence);
 
 The caller pass the out-fence and gets back the sync_file. That is just the
 first step, next it needs to install an fd on sync_file->file. So it gets an
-fd:
+fd::
 
 	fd = get_unused_fd_flags(O_CLOEXEC);
 
-and installs it on sync_file->file:
+and installs it on sync_file->file::
 
 	fd_install(fd, sync_file->file);
 
@@ -71,7 +72,8 @@ When userspace needs to send an in-fence to the driver it passes file descriptor
 of the Sync File to the kernel. The kernel can then retrieve the fences
 from it.
 
-Interface:
+Interface::
+
 	struct dma_fence *sync_file_get_fence(int fd);
 
 
@@ -79,5 +81,6 @@ The returned reference is owned by the caller and must be disposed of
 afterwards using dma_fence_put(). In case of error, a NULL is returned instead.
 
 References:
-[1] struct sync_file in include/linux/sync_file.h
-[2] All interfaces mentioned above defined in include/linux/sync_file.h
+
+1. struct sync_file in include/linux/sync_file.h
+2. All interfaces mentioned above defined in include/linux/sync_file.h
-- 
2.9.4

[PATCH 21/29] this_cpu_ops.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote document title one level;
- mark literal blocks;
- move authorship to the beginning of the file and use markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/this_cpu_ops.txt | 49 ++++++++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 21 deletions(-)

diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.txt
index 2cbf71975381..5cb8b883ae83 100644
--- a/Documentation/this_cpu_ops.txt
+++ b/Documentation/this_cpu_ops.txt
@@ -1,5 +1,9 @@
+===================
 this_cpu operations
--------------------
+===================
+
+:Author: Christoph Lameter, August 4th, 2014
+:Author: Pranith Kumar, Aug 2nd, 2014
 
 this_cpu operations are a way of optimizing access to per cpu
 variables associated with the *currently* executing processor. This is
@@ -39,7 +43,7 @@ operations.
 
 The following this_cpu() operations with implied preemption protection
 are defined. These operations can be used without worrying about
-preemption and interrupts.
+preemption and interrupts::
 
 	this_cpu_read(pcp)
 	this_cpu_write(pcp, val)
@@ -67,14 +71,14 @@ to relocate a per cpu relative address to the proper per cpu area for
 the processor. So the relocation to the per cpu base is encoded in the
 instruction via a segment register prefix.
 
-For example:
+For example::
 
 	DEFINE_PER_CPU(int, x);
 	int z;
 
 	z = this_cpu_read(x);
 
-results in a single instruction
+results in a single instruction::
 
 	mov ax, gs:[x]
 
@@ -84,16 +88,16 @@ this_cpu_ops such sequence also required preempt disable/enable to
 prevent the kernel from moving the thread to a different processor
 while the calculation is performed.
 
-Consider the following this_cpu operation:
+Consider the following this_cpu operation::
 
 	this_cpu_inc(x)
 
-The above results in the following single instruction (no lock prefix!)
+The above results in the following single instruction (no lock prefix!)::
 
 	inc gs:[x]
 
 instead of the following operations required if there is no segment
-register:
+register::
 
 	int *y;
 	int cpu;
@@ -121,8 +125,10 @@ has to be paid for this optimization is the need to add up the per cpu
 counters when the value of a counter is needed.
 
 
-Special operations:
--------------------
+Special operations
+------------------
+
+::
 
 	y = this_cpu_ptr(&x)
 
@@ -153,11 +159,15 @@ Therefore the use of x or &x outside of the context of per cpu
 operations is invalid and will generally be treated like a NULL
 pointer dereference.
 
+::
+
 	DEFINE_PER_CPU(int, x);
 
 In the context of per cpu operations the above implies that x is a per
 cpu variable. Most this_cpu operations take a cpu variable.
 
+::
+
 	int __percpu *p = &x;
 
 &x and hence p is the *offset* of a per cpu variable. this_cpu_ptr()
@@ -168,7 +178,7 @@ strange.
 Operations on a field of a per cpu structure
 --------------------------------------------
 
-Let's say we have a percpu structure
+Let's say we have a percpu structure::
 
 	struct s {
 		int n,m;
@@ -177,14 +187,14 @@ Let's say we have a percpu structure
 	DEFINE_PER_CPU(struct s, p);
 
 
-Operations on these fields are straightforward
+Operations on these fields are straightforward::
 
 	this_cpu_inc(p.m)
 
 	z = this_cpu_cmpxchg(p.m, 0, 1);
 
 
-If we have an offset to struct s:
+If we have an offset to struct s::
 
 	struct s __percpu *ps = &p;
 
@@ -194,7 +204,7 @@ If we have an offset to struct s:
 
 
 The calculation of the pointer may require the use of this_cpu_ptr()
-if we do not make use of this_cpu ops later to manipulate fields:
+if we do not make use of this_cpu ops later to manipulate fields::
 
 	struct s *pp;
 
@@ -206,7 +216,7 @@ if we do not make use of this_cpu ops later to manipulate fields:
 
 
 Variants of this_cpu ops
--------------------------
+------------------------
 
 this_cpu ops are interrupt safe. Some architectures do not support
 these per cpu local operations. In that case the operation must be
@@ -222,7 +232,7 @@ preemption. If a per cpu variable is not used in an interrupt context
 and the scheduler cannot preempt, then they are safe. If any interrupts
 still occur while an operation is in progress and if the interrupt too
 modifies the variable, then RMW actions can not be guaranteed to be
-safe.
+safe::
 
 	__this_cpu_read(pcp)
 	__this_cpu_write(pcp, val)
@@ -279,7 +289,7 @@ unless absolutely necessary. Please consider using an IPI to wake up
 the remote CPU and perform the update to its per cpu area.
 
 To access per-cpu data structure remotely, typically the per_cpu_ptr()
-function is used:
+function is used::
 
 
 	DEFINE_PER_CPU(struct data, datap);
@@ -289,7 +299,7 @@ function is used:
 This makes it explicit that we are getting ready to access a percpu
 area remotely.
 
-You can also do the following to convert the datap offset to an address
+You can also do the following to convert the datap offset to an address::
 
 	struct data *p = this_cpu_ptr(&datap);
 
@@ -305,7 +315,7 @@ the following scenario that occurs because two per cpu variables
 share a cache-line but the relaxed synchronization is applied to
 only one process updating the cache-line.
 
-Consider the following example
+Consider the following example::
 
 
 	struct test {
@@ -327,6 +337,3 @@ mind that a remote write will evict the cache line from the processor
 that most likely will access it. If the processor wakes up and finds a
 missing local cache line of a per cpu area, its performance and hence
 the wake up times will be affected.
-
-Christoph Lameter, August 4th, 2014
-Pranith Kumar, Aug 2nd, 2014
-- 
2.9.4

[PATCH 22/29] unaligned-memory-access.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote document title one level;
- use markups for authorship and put it at the beginning;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/unaligned-memory-access.txt | 57 ++++++++++++++++---------------
 1 file changed, 30 insertions(+), 27 deletions(-)

diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt
index 3f76c0c37920..51b4ff031586 100644
--- a/Documentation/unaligned-memory-access.txt
+++ b/Documentation/unaligned-memory-access.txt
@@ -1,6 +1,15 @@
+=========================
 UNALIGNED MEMORY ACCESSES
 =========================
 
+:Author: Daniel Drake <dsd@gentoo.org>,
+:Author: Johannes Berg <johannes@sipsolutions.net>
+
+:With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt,
+  Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz,
+  Vadim Lobanov
+
+
 Linux runs on a wide variety of architectures which have varying behaviour
 when it comes to memory access. This document presents some details about
 unaligned accesses, why you need to write code that doesn't cause them,
@@ -73,7 +82,7 @@ memory addresses of certain variables, etc.
 
 Fortunately things are not too complex, as in most cases, the compiler
 ensures that things will work for you. For example, take the following
-structure:
+structure::
 
 	struct foo {
 		u16 field1;
@@ -106,7 +115,7 @@ On a related topic, with the above considerations in mind you may observe
 that you could reorder the fields in the structure in order to place fields
 where padding would otherwise be inserted, and hence reduce the overall
 resident memory size of structure instances. The optimal layout of the
-above example is:
+above example is::
 
 	struct foo {
 		u32 field2;
@@ -139,21 +148,21 @@ Code that causes unaligned access
 With the above in mind, let's move onto a real life example of a function
 that can cause an unaligned memory access. The following function taken
 from include/linux/etherdevice.h is an optimized routine to compare two
-ethernet MAC addresses for equality.
+ethernet MAC addresses for equality::
 
-bool ether_addr_equal(const u8 *addr1, const u8 *addr2)
-{
-#ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
+  bool ether_addr_equal(const u8 *addr1, const u8 *addr2)
+  {
+  #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
 	u32 fold = ((*(const u32 *)addr1) ^ (*(const u32 *)addr2)) |
 		   ((*(const u16 *)(addr1 + 4)) ^ (*(const u16 *)(addr2 + 4)));
 
 	return fold == 0;
-#else
+  #else
 	const u16 *a = (const u16 *)addr1;
 	const u16 *b = (const u16 *)addr2;
 	return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) == 0;
-#endif
-}
+  #endif
+  }
 
 In the above function, when the hardware has efficient unaligned access
 capability, there is no issue with this code.  But when the hardware isn't
@@ -171,7 +180,8 @@ as it is a decent optimization for the cases when you can ensure alignment,
 which is true almost all of the time in ethernet networking context.
 
 
-Here is another example of some code that could cause unaligned accesses:
+Here is another example of some code that could cause unaligned accesses::
+
 	void myfunc(u8 *data, u32 value)
 	{
 		[...]
@@ -184,6 +194,7 @@ to an address that is not evenly divisible by 4.
 
 In summary, the 2 main scenarios where you may run into unaligned access
 problems involve:
+
  1. Casting variables to types of different lengths
  2. Pointer arithmetic followed by access to at least 2 bytes of data
 
@@ -195,7 +206,7 @@ The easiest way to avoid unaligned access is to use the get_unaligned() and
 put_unaligned() macros provided by the <asm/unaligned.h> header file.
 
 Going back to an earlier example of code that potentially causes unaligned
-access:
+access::
 
 	void myfunc(u8 *data, u32 value)
 	{
@@ -204,7 +215,7 @@ access:
 		[...]
 	}
 
-To avoid the unaligned memory access, you would rewrite it as follows:
+To avoid the unaligned memory access, you would rewrite it as follows::
 
 	void myfunc(u8 *data, u32 value)
 	{
@@ -215,7 +226,7 @@ To avoid the unaligned memory access, you would rewrite it as follows:
 	}
 
 The get_unaligned() macro works similarly. Assuming 'data' is a pointer to
-memory and you wish to avoid unaligned access, its usage is as follows:
+memory and you wish to avoid unaligned access, its usage is as follows::
 
 	u32 value = get_unaligned((u32 *) data);
 
@@ -245,18 +256,10 @@ For some ethernet hardware that cannot DMA to unaligned addresses like
 4*n+2 or non-ethernet hardware, this can be a problem, and it is then
 required to copy the incoming frame into an aligned buffer. Because this is
 unnecessary on architectures that can do unaligned accesses, the code can be
-made dependent on CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS like so:
-
-#ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
-	skb = original skb
-#else
-	skb = copy skb
-#endif
-
---
-Authors: Daniel Drake <dsd@gentoo.org>,
-         Johannes Berg <johannes@sipsolutions.net>
-With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt,
-Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz,
-Vadim Lobanov
+made dependent on CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS like so::
 
+	#ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS
+		skb = original skb
+	#else
+		skb = copy skb
+	#endif
-- 
2.9.4

[PATCH 23/29] vfio-mediated-device.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

In this specific document, the title, copyright and authorship
are added as if it were a C file!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- convert document preambule to the proper format;
- mark literal blocks;
- adjust identation;
- use numbered lists for references.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/vfio-mediated-device.txt | 252 +++++++++++++++++----------------
 1 file changed, 130 insertions(+), 122 deletions(-)

diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
index e5e57b40f8af..1b3950346532 100644
--- a/Documentation/vfio-mediated-device.txt
+++ b/Documentation/vfio-mediated-device.txt
@@ -1,14 +1,17 @@
-/*
- * VFIO Mediated devices
- *
- * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
- *     Author: Neo Jia <cjia@nvidia.com>
- *             Kirti Wankhede <kwankhede@nvidia.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- */
+.. include:: <isonum.txt>
+
+=====================
+VFIO Mediated devices
+=====================
+
+:Copyright: |copy| 2016, NVIDIA CORPORATION. All rights reserved.
+:Author: Neo Jia <cjia@nvidia.com>
+:Author: Kirti Wankhede <kwankhede@nvidia.com>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
 
 Virtual Function I/O (VFIO) Mediated devices[1]
 ===============================================
@@ -42,7 +45,7 @@ removes it from a VFIO group.
 
 The following high-level block diagram shows the main components and interfaces
 in the VFIO mediated driver framework. The diagram shows NVIDIA, Intel, and IBM
-devices as examples, as these devices are the first devices to use this module.
+devices as examples, as these devices are the first devices to use this module::
 
      +---------------+
      |               |
@@ -91,7 +94,7 @@ Registration Interface for a Mediated Bus Driver
 ------------------------------------------------
 
 The registration interface for a mediated bus driver provides the following
-structure to represent a mediated device's driver:
+structure to represent a mediated device's driver::
 
      /*
       * struct mdev_driver [2] - Mediated device's driver
@@ -110,14 +113,14 @@ structure to represent a mediated device's driver:
 A mediated bus driver for mdev should use this structure in the function calls
 to register and unregister itself with the core driver:
 
-* Register:
+* Register::
 
-  extern int  mdev_register_driver(struct mdev_driver *drv,
+    extern int  mdev_register_driver(struct mdev_driver *drv,
 				   struct module *owner);
 
-* Unregister:
+* Unregister::
 
-  extern void mdev_unregister_driver(struct mdev_driver *drv);
+    extern void mdev_unregister_driver(struct mdev_driver *drv);
 
 The mediated bus driver is responsible for adding mediated devices to the VFIO
 group when devices are bound to the driver and removing mediated devices from
@@ -152,15 +155,15 @@ The callbacks in the mdev_parent_ops structure are as follows:
 * mmap: mmap emulation callback
 
 A driver should use the mdev_parent_ops structure in the function call to
-register itself with the mdev core driver:
+register itself with the mdev core driver::
 
-extern int  mdev_register_device(struct device *dev,
-                                 const struct mdev_parent_ops *ops);
+	extern int  mdev_register_device(struct device *dev,
+	                                 const struct mdev_parent_ops *ops);
 
 However, the mdev_parent_ops structure is not required in the function call
-that a driver should use to unregister itself with the mdev core driver:
+that a driver should use to unregister itself with the mdev core driver::
 
-extern void mdev_unregister_device(struct device *dev);
+	extern void mdev_unregister_device(struct device *dev);
 
 
 Mediated Device Management Interface Through sysfs
@@ -183,30 +186,32 @@ with the mdev core driver.
 Directories and files under the sysfs for Each Physical Device
 --------------------------------------------------------------
 
-|- [parent physical device]
-|--- Vendor-specific-attributes [optional]
-|--- [mdev_supported_types]
-|     |--- [<type-id>]
-|     |   |--- create
-|     |   |--- name
-|     |   |--- available_instances
-|     |   |--- device_api
-|     |   |--- description
-|     |   |--- [devices]
-|     |--- [<type-id>]
-|     |   |--- create
-|     |   |--- name
-|     |   |--- available_instances
-|     |   |--- device_api
-|     |   |--- description
-|     |   |--- [devices]
-|     |--- [<type-id>]
-|          |--- create
-|          |--- name
-|          |--- available_instances
-|          |--- device_api
-|          |--- description
-|          |--- [devices]
+::
+
+  |- [parent physical device]
+  |--- Vendor-specific-attributes [optional]
+  |--- [mdev_supported_types]
+  |     |--- [<type-id>]
+  |     |   |--- create
+  |     |   |--- name
+  |     |   |--- available_instances
+  |     |   |--- device_api
+  |     |   |--- description
+  |     |   |--- [devices]
+  |     |--- [<type-id>]
+  |     |   |--- create
+  |     |   |--- name
+  |     |   |--- available_instances
+  |     |   |--- device_api
+  |     |   |--- description
+  |     |   |--- [devices]
+  |     |--- [<type-id>]
+  |          |--- create
+  |          |--- name
+  |          |--- available_instances
+  |          |--- device_api
+  |          |--- description
+  |          |--- [devices]
 
 * [mdev_supported_types]
 
@@ -219,12 +224,12 @@ Directories and files under the sysfs for Each Physical Device
 
   The [<type-id>] name is created by adding the device driver string as a prefix
   to the string provided by the vendor driver. This format of this name is as
-  follows:
+  follows::
 
 	sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name);
 
   (or using mdev_parent_dev(mdev) to arrive at the parent device outside
-   of the core mdev code)
+  of the core mdev code)
 
 * device_api
 
@@ -239,7 +244,7 @@ Directories and files under the sysfs for Each Physical Device
 * [device]
 
   This directory contains links to the devices of type <type-id> that have been
-created.
+  created.
 
 * name
 
@@ -253,21 +258,25 @@ created.
 Directories and Files Under the sysfs for Each mdev Device
 ----------------------------------------------------------
 
-|- [parent phy device]
-|--- [$MDEV_UUID]
+::
+
+  |- [parent phy device]
+  |--- [$MDEV_UUID]
          |--- remove
          |--- mdev_type {link to its type}
          |--- vendor-specific-attributes [optional]
 
 * remove (write only)
+
 Writing '1' to the 'remove' file destroys the mdev device. The vendor driver can
 fail the remove() callback if that device is active and the vendor driver
 doesn't support hot unplug.
 
-Example:
+Example::
+
 	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
 
-Mediated device Hot plug:
+Mediated device Hot plug
 ------------------------
 
 Mediated devices can be created and assigned at runtime. The procedure to hot
@@ -277,13 +286,13 @@ Translation APIs for Mediated Devices
 =====================================
 
 The following APIs are provided for translating user pfn to host pfn in a VFIO
-driver:
+driver::
 
-extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
-                          int npage, int prot, unsigned long *phys_pfn);
+	extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
+				  int npage, int prot, unsigned long *phys_pfn);
 
-extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
-                            int npage);
+	extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
+				    int npage);
 
 These functions call back into the back-end IOMMU module by using the pin_pages
 and unpin_pages callbacks of the struct vfio_iommu_driver_ops[4]. Currently
@@ -304,81 +313,80 @@ card.
 
    This step creates a dummy device, /sys/devices/virtual/mtty/mtty/
 
-   Files in this device directory in sysfs are similar to the following:
+   Files in this device directory in sysfs are similar to the following::
 
-   # tree /sys/devices/virtual/mtty/mtty/
-      /sys/devices/virtual/mtty/mtty/
-      |-- mdev_supported_types
-      |   |-- mtty-1
-      |   |   |-- available_instances
-      |   |   |-- create
-      |   |   |-- device_api
-      |   |   |-- devices
-      |   |   `-- name
-      |   `-- mtty-2
-      |       |-- available_instances
-      |       |-- create
-      |       |-- device_api
-      |       |-- devices
-      |       `-- name
-      |-- mtty_dev
-      |   `-- sample_mtty_dev
-      |-- power
-      |   |-- autosuspend_delay_ms
-      |   |-- control
-      |   |-- runtime_active_time
-      |   |-- runtime_status
-      |   `-- runtime_suspended_time
-      |-- subsystem -> ../../../../class/mtty
-      `-- uevent
+     # tree /sys/devices/virtual/mtty/mtty/
+        /sys/devices/virtual/mtty/mtty/
+        |-- mdev_supported_types
+        |   |-- mtty-1
+        |   |   |-- available_instances
+        |   |   |-- create
+        |   |   |-- device_api
+        |   |   |-- devices
+        |   |   `-- name
+        |   `-- mtty-2
+        |       |-- available_instances
+        |       |-- create
+        |       |-- device_api
+        |       |-- devices
+        |       `-- name
+        |-- mtty_dev
+        |   `-- sample_mtty_dev
+        |-- power
+        |   |-- autosuspend_delay_ms
+        |   |-- control
+        |   |-- runtime_active_time
+        |   |-- runtime_status
+        |   `-- runtime_suspended_time
+        |-- subsystem -> ../../../../class/mtty
+        `-- uevent
 
 2. Create a mediated device by using the dummy device that you created in the
-   previous step.
+   previous step::
 
-   # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
+     # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
               /sys/devices/virtual/mtty/mtty/mdev_supported_types/mtty-2/create
 
-3. Add parameters to qemu-kvm.
+3. Add parameters to qemu-kvm::
 
-   -device vfio-pci,\
-    sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
+     -device vfio-pci,\
+      sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
 
 4. Boot the VM.
 
    In the Linux guest VM, with no hardware on the host, the device appears
-   as  follows:
+   as  follows::
 
-   # lspci -s 00:05.0 -xxvv
-   00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
-           Subsystem: Device 4348:3253
-           Physical Slot: 5
-           Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
-   Stepping- SERR- FastB2B- DisINTx-
-           Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
-   <TAbort- <MAbort- >SERR- <PERR- INTx-
-           Interrupt: pin A routed to IRQ 10
-           Region 0: I/O ports at c150 [size=8]
-           Region 1: I/O ports at c158 [size=8]
-           Kernel driver in use: serial
-   00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
-   10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
-   20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
-   30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
+     # lspci -s 00:05.0 -xxvv
+     00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
+             Subsystem: Device 4348:3253
+             Physical Slot: 5
+             Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
+     Stepping- SERR- FastB2B- DisINTx-
+             Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
+     <TAbort- <MAbort- >SERR- <PERR- INTx-
+             Interrupt: pin A routed to IRQ 10
+             Region 0: I/O ports at c150 [size=8]
+             Region 1: I/O ports at c158 [size=8]
+             Kernel driver in use: serial
+     00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
+     10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
+     20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
+     30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
 
-   In the Linux guest VM, dmesg output for the device is as follows:
+     In the Linux guest VM, dmesg output for the device is as follows:
 
-   serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ
-10
-   0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
-   0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
+     serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ 10
+     0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
+     0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
 
 
-5. In the Linux guest VM, check the serial ports.
+5. In the Linux guest VM, check the serial ports::
 
-   # setserial -g /dev/ttyS*
-   /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
-   /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
-   /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
+     # setserial -g /dev/ttyS*
+     /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
+     /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
+     /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
 
 6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
    /dev/ttyS2 with hardware flow control disabled.
@@ -388,14 +396,14 @@ card.
 
    Data is loop backed from hosts mtty driver.
 
-8. Destroy the mediated device that you created.
+8. Destroy the mediated device that you created::
 
-   # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
+     # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
 
 References
 ==========
 
-[1] See Documentation/vfio.txt 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
+1. See Documentation/vfio.txt 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
-- 
2.9.4

[PATCH 24/29] vfio.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- adjust title marks;
- use footnote marks;
- mark literal blocks;
- adjust identation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/vfio.txt | 261 +++++++++++++++++++++++++------------------------
 1 file changed, 134 insertions(+), 127 deletions(-)

diff --git a/Documentation/vfio.txt b/Documentation/vfio.txt
index 1dd3fddfd3a1..ef6a5111eaa1 100644
--- a/Documentation/vfio.txt
+++ b/Documentation/vfio.txt
@@ -1,5 +1,7 @@
-VFIO - "Virtual Function I/O"[1]
--------------------------------------------------------------------------------
+==================================
+VFIO - "Virtual Function I/O" [1]_
+==================================
+
 Many modern system now provide DMA and interrupt remapping facilities
 to help ensure I/O devices behave within the boundaries they've been
 allotted.  This includes x86 hardware with AMD-Vi and Intel VT-d,
@@ -7,14 +9,14 @@ POWER systems with Partitionable Endpoints (PEs) and embedded PowerPC
 systems such as Freescale PAMU.  The VFIO driver is an IOMMU/device
 agnostic framework for exposing direct device access to userspace, in
 a secure, IOMMU protected environment.  In other words, this allows
-safe[2], non-privileged, userspace drivers.
+safe [2]_, non-privileged, userspace drivers.
 
 Why do we want that?  Virtual machines often make use of direct device
 access ("device assignment") when configured for the highest possible
 I/O performance.  From a device and host perspective, this simply
 turns the VM into a userspace driver, with the benefits of
 significantly reduced latency, higher bandwidth, and direct use of
-bare-metal device drivers[3].
+bare-metal device drivers [3]_.
 
 Some applications, particularly in the high performance computing
 field, also benefit from low-overhead, direct device access from
@@ -31,7 +33,7 @@ KVM PCI specific device assignment code as well as provide a more
 secure, more featureful userspace driver environment than UIO.
 
 Groups, Devices, and IOMMUs
--------------------------------------------------------------------------------
+---------------------------
 
 Devices are the main target of any I/O driver.  Devices typically
 create a programming interface made up of I/O access, interrupts,
@@ -114,40 +116,40 @@ well as mechanisms for describing and registering interrupt
 notifications.
 
 VFIO Usage Example
--------------------------------------------------------------------------------
+------------------
 
-Assume user wants to access PCI device 0000:06:0d.0
+Assume user wants to access PCI device 0000:06:0d.0::
 
-$ readlink /sys/bus/pci/devices/0000:06:0d.0/iommu_group
-../../../../kernel/iommu_groups/26
+	$ readlink /sys/bus/pci/devices/0000:06:0d.0/iommu_group
+	../../../../kernel/iommu_groups/26
 
 This device is therefore in IOMMU group 26.  This device is on the
 pci bus, therefore the user will make use of vfio-pci to manage the
-group:
+group::
 
-# modprobe vfio-pci
+	# modprobe vfio-pci
 
 Binding this device to the vfio-pci driver creates the VFIO group
-character devices for this group:
+character devices for this group::
 
-$ lspci -n -s 0000:06:0d.0
-06:0d.0 0401: 1102:0002 (rev 08)
-# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
-# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
+	$ lspci -n -s 0000:06:0d.0
+	06:0d.0 0401: 1102:0002 (rev 08)
+	# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
+	# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
 
 Now we need to look at what other devices are in the group to free
-it for use by VFIO:
+it for use by VFIO::
 
-$ ls -l /sys/bus/pci/devices/0000:06:0d.0/iommu_group/devices
-total 0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:00:1e.0 ->
-	../../../../devices/pci0000:00/0000:00:1e.0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.0 ->
-	../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.1 ->
-	../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.1
+	$ ls -l /sys/bus/pci/devices/0000:06:0d.0/iommu_group/devices
+	total 0
+	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:00:1e.0 ->
+		../../../../devices/pci0000:00/0000:00:1e.0
+	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.0 ->
+		../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.0
+	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.1 ->
+		../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.1
 
-This device is behind a PCIe-to-PCI bridge[4], therefore we also
+This device is behind a PCIe-to-PCI bridge [4]_, therefore we also
 need to add device 0000:06:0d.1 to the group following the same
 procedure as above.  Device 0000:00:1e.0 is a bridge that does
 not currently have a host driver, therefore it's not required to
@@ -157,12 +159,12 @@ support PCI bridges).
 The final step is to provide the user with access to the group if
 unprivileged operation is desired (note that /dev/vfio/vfio provides
 no capabilities on its own and is therefore expected to be set to
-mode 0666 by the system).
+mode 0666 by the system)::
 
-# chown user:user /dev/vfio/26
+	# chown user:user /dev/vfio/26
 
 The user now has full access to all the devices and the iommu for this
-group and can access them as follows:
+group and can access them as follows::
 
 	int container, group, device, i;
 	struct vfio_group_status group_status =
@@ -248,31 +250,31 @@ VFIO bus driver API
 VFIO bus drivers, such as vfio-pci make use of only a few interfaces
 into VFIO core.  When devices are bound and unbound to the driver,
 the driver should call vfio_add_group_dev() and vfio_del_group_dev()
-respectively:
+respectively::
 
-extern int vfio_add_group_dev(struct iommu_group *iommu_group,
-                              struct device *dev,
-                              const struct vfio_device_ops *ops,
-                              void *device_data);
+	extern int vfio_add_group_dev(struct iommu_group *iommu_group,
+	                              struct device *dev,
+				      const struct vfio_device_ops *ops,
+				      void *device_data);
 
-extern void *vfio_del_group_dev(struct device *dev);
+	extern void *vfio_del_group_dev(struct device *dev);
 
 vfio_add_group_dev() indicates to the core to begin tracking the
 specified iommu_group and register the specified dev as owned by
 a VFIO bus driver.  The driver provides an ops structure for callbacks
-similar to a file operations structure:
+similar to a file operations structure::
 
-struct vfio_device_ops {
-	int	(*open)(void *device_data);
-	void	(*release)(void *device_data);
-	ssize_t	(*read)(void *device_data, char __user *buf,
-			size_t count, loff_t *ppos);
-	ssize_t	(*write)(void *device_data, const char __user *buf,
-			 size_t size, loff_t *ppos);
-	long	(*ioctl)(void *device_data, unsigned int cmd,
-			 unsigned long arg);
-	int	(*mmap)(void *device_data, struct vm_area_struct *vma);
-};
+	struct vfio_device_ops {
+		int	(*open)(void *device_data);
+		void	(*release)(void *device_data);
+		ssize_t	(*read)(void *device_data, char __user *buf,
+				size_t count, loff_t *ppos);
+		ssize_t	(*write)(void *device_data, const char __user *buf,
+				 size_t size, loff_t *ppos);
+		long	(*ioctl)(void *device_data, unsigned int cmd,
+				 unsigned long arg);
+		int	(*mmap)(void *device_data, struct vm_area_struct *vma);
+	};
 
 Each function is passed the device_data that was originally registered
 in the vfio_add_group_dev() call above.  This allows the bus driver
@@ -285,50 +287,55 @@ own VFIO_DEVICE_GET_REGION_INFO ioctl.
 
 
 PPC64 sPAPR implementation note
--------------------------------------------------------------------------------
+-------------------------------
 
 This implementation has some specifics:
 
 1) On older systems (POWER7 with P5IOC2/IODA1) only one IOMMU group per
-container is supported as an IOMMU table is allocated at the boot time,
-one table per a IOMMU group which is a Partitionable Endpoint (PE)
-(PE is often a PCI domain but not always).
-Newer systems (POWER8 with IODA2) have improved hardware design which allows
-to remove this limitation and have multiple IOMMU groups per a VFIO container.
+   container is supported as an IOMMU table is allocated at the boot time,
+   one table per a IOMMU group which is a Partitionable Endpoint (PE)
+   (PE is often a PCI domain but not always).
+
+   Newer systems (POWER8 with IODA2) have improved hardware design which allows
+   to remove this limitation and have multiple IOMMU groups per a VFIO
+   container.
 
 2) The hardware supports so called DMA windows - the PCI address range
-within which DMA transfer is allowed, any attempt to access address space
-out of the window leads to the whole PE isolation.
+   within which DMA transfer is allowed, any attempt to access address space
+   out of the window leads to the whole PE isolation.
 
 3) PPC64 guests are paravirtualized but not fully emulated. There is an API
-to map/unmap pages for DMA, and it normally maps 1..32 pages per call and
-currently there is no way to reduce the number of calls. In order to make things
-faster, the map/unmap handling has been implemented in real mode which provides
-an excellent performance which has limitations such as inability to do
-locked pages accounting in real time.
+   to map/unmap pages for DMA, and it normally maps 1..32 pages per call and
+   currently there is no way to reduce the number of calls. In order to make
+   things faster, the map/unmap handling has been implemented in real mode
+   which provides an excellent performance which has limitations such as
+   inability to do locked pages accounting in real time.
 
 4) According to sPAPR specification, A Partitionable Endpoint (PE) is an I/O
-subtree that can be treated as a unit for the purposes of partitioning and
-error recovery. A PE may be a single or multi-function IOA (IO Adapter), a
-function of a multi-function IOA, or multiple IOAs (possibly including switch
-and bridge structures above the multiple IOAs). PPC64 guests detect PCI errors
-and recover from them via EEH RTAS services, which works on the basis of
-additional ioctl commands.
+   subtree that can be treated as a unit for the purposes of partitioning and
+   error recovery. A PE may be a single or multi-function IOA (IO Adapter), a
+   function of a multi-function IOA, or multiple IOAs (possibly including
+   switch and bridge structures above the multiple IOAs). PPC64 guests detect
+   PCI errors and recover from them via EEH RTAS services, which works on the
+   basis of additional ioctl commands.
 
-So 4 additional ioctls have been added:
+   So 4 additional ioctls have been added:
 
-	VFIO_IOMMU_SPAPR_TCE_GET_INFO - returns the size and the start
-		of the DMA window on the PCI bus.
+	VFIO_IOMMU_SPAPR_TCE_GET_INFO
+		returns the size and the start of the DMA window on the PCI bus.
 
-	VFIO_IOMMU_ENABLE - enables the container. The locked pages accounting
+	VFIO_IOMMU_ENABLE
+		enables the container. The locked pages accounting
 		is done at this point. This lets user first to know what
 		the DMA window is and adjust rlimit before doing any real job.
 
-	VFIO_IOMMU_DISABLE - disables the container.
+	VFIO_IOMMU_DISABLE
+		disables the container.
 
-	VFIO_EEH_PE_OP - provides an API for EEH setup, error detection and recovery.
+	VFIO_EEH_PE_OP
+		provides an API for EEH setup, error detection and recovery.
 
-The code flow from the example above should be slightly changed:
+   The code flow from the example above should be slightly changed::
 
 	struct vfio_eeh_pe_op pe_op = { .argsz = sizeof(pe_op), .flags = 0 };
 
@@ -442,73 +449,73 @@ The code flow from the example above should be slightly changed:
 	....
 
 5) There is v2 of SPAPR TCE IOMMU. It deprecates VFIO_IOMMU_ENABLE/
-VFIO_IOMMU_DISABLE and implements 2 new ioctls:
-VFIO_IOMMU_SPAPR_REGISTER_MEMORY and VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY
-(which are unsupported in v1 IOMMU).
+   VFIO_IOMMU_DISABLE and implements 2 new ioctls:
+   VFIO_IOMMU_SPAPR_REGISTER_MEMORY and VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY
+   (which are unsupported in v1 IOMMU).
 
-PPC64 paravirtualized guests generate a lot of map/unmap requests,
-and the handling of those includes pinning/unpinning pages and updating
-mm::locked_vm counter to make sure we do not exceed the rlimit.
-The v2 IOMMU splits accounting and pinning into separate operations:
+   PPC64 paravirtualized guests generate a lot of map/unmap requests,
+   and the handling of those includes pinning/unpinning pages and updating
+   mm::locked_vm counter to make sure we do not exceed the rlimit.
+   The v2 IOMMU splits accounting and pinning into separate operations:
 
-- VFIO_IOMMU_SPAPR_REGISTER_MEMORY/VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY ioctls
-receive a user space address and size of the block to be pinned.
-Bisecting is not supported and VFIO_IOMMU_UNREGISTER_MEMORY is expected to
-be called with the exact address and size used for registering
-the memory block. The userspace is not expected to call these often.
-The ranges are stored in a linked list in a VFIO container.
+   - VFIO_IOMMU_SPAPR_REGISTER_MEMORY/VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY ioctls
+     receive a user space address and size of the block to be pinned.
+     Bisecting is not supported and VFIO_IOMMU_UNREGISTER_MEMORY is expected to
+     be called with the exact address and size used for registering
+     the memory block. The userspace is not expected to call these often.
+     The ranges are stored in a linked list in a VFIO container.
 
-- VFIO_IOMMU_MAP_DMA/VFIO_IOMMU_UNMAP_DMA ioctls only update the actual
-IOMMU table and do not do pinning; instead these check that the userspace
-address is from pre-registered range.
+   - VFIO_IOMMU_MAP_DMA/VFIO_IOMMU_UNMAP_DMA ioctls only update the actual
+     IOMMU table and do not do pinning; instead these check that the userspace
+     address is from pre-registered range.
 
-This separation helps in optimizing DMA for guests.
+   This separation helps in optimizing DMA for guests.
 
 6) sPAPR specification allows guests to have an additional DMA window(s) on
-a PCI bus with a variable page size. Two ioctls have been added to support
-this: VFIO_IOMMU_SPAPR_TCE_CREATE and VFIO_IOMMU_SPAPR_TCE_REMOVE.
-The platform has to support the functionality or error will be returned to
-the userspace. The existing hardware supports up to 2 DMA windows, one is
-2GB long, uses 4K pages and called "default 32bit window"; the other can
-be as big as entire RAM, use different page size, it is optional - guests
-create those in run-time if the guest driver supports 64bit DMA.
+   a PCI bus with a variable page size. Two ioctls have been added to support
+   this: VFIO_IOMMU_SPAPR_TCE_CREATE and VFIO_IOMMU_SPAPR_TCE_REMOVE.
+   The platform has to support the functionality or error will be returned to
+   the userspace. The existing hardware supports up to 2 DMA windows, one is
+   2GB long, uses 4K pages and called "default 32bit window"; the other can
+   be as big as entire RAM, use different page size, it is optional - guests
+   create those in run-time if the guest driver supports 64bit DMA.
 
-VFIO_IOMMU_SPAPR_TCE_CREATE receives a page shift, a DMA window size and
-a number of TCE table levels (if a TCE table is going to be big enough and
-the kernel may not be able to allocate enough of physically contiguous memory).
-It creates a new window in the available slot and returns the bus address where
-the new window starts. Due to hardware limitation, the user space cannot choose
-the location of DMA windows.
+   VFIO_IOMMU_SPAPR_TCE_CREATE receives a page shift, a DMA window size and
+   a number of TCE table levels (if a TCE table is going to be big enough and
+   the kernel may not be able to allocate enough of physically contiguous
+   memory). It creates a new window in the available slot and returns the bus
+   address where the new window starts. Due to hardware limitation, the user
+   space cannot choose the location of DMA windows.
 
-VFIO_IOMMU_SPAPR_TCE_REMOVE receives the bus start address of the window
-and removes it.
+   VFIO_IOMMU_SPAPR_TCE_REMOVE receives the bus start address of the window
+   and removes it.
 
 -------------------------------------------------------------------------------
 
-[1] VFIO was originally an acronym for "Virtual Function I/O" in its
-initial implementation by Tom Lyon while as Cisco.  We've since
-outgrown the acronym, but it's catchy.
+.. [1] VFIO was originally an acronym for "Virtual Function I/O" in its
+   initial implementation by Tom Lyon while as Cisco.  We've since
+   outgrown the acronym, but it's catchy.
 
-[2] "safe" also depends upon a device being "well behaved".  It's
-possible for multi-function devices to have backdoors between
-functions and even for single function devices to have alternative
-access to things like PCI config space through MMIO registers.  To
-guard against the former we can include additional precautions in the
-IOMMU driver to group multi-function PCI devices together
-(iommu=group_mf).  The latter we can't prevent, but the IOMMU should
-still provide isolation.  For PCI, SR-IOV Virtual Functions are the
-best indicator of "well behaved", as these are designed for
-virtualization usage models.
+.. [2] "safe" also depends upon a device being "well behaved".  It's
+   possible for multi-function devices to have backdoors between
+   functions and even for single function devices to have alternative
+   access to things like PCI config space through MMIO registers.  To
+   guard against the former we can include additional precautions in the
+   IOMMU driver to group multi-function PCI devices together
+   (iommu=group_mf).  The latter we can't prevent, but the IOMMU should
+   still provide isolation.  For PCI, SR-IOV Virtual Functions are the
+   best indicator of "well behaved", as these are designed for
+   virtualization usage models.
 
-[3] As always there are trade-offs to virtual machine device
-assignment that are beyond the scope of VFIO.  It's expected that
-future IOMMU technologies will reduce some, but maybe not all, of
-these trade-offs.
+.. [3] As always there are trade-offs to virtual machine device
+   assignment that are beyond the scope of VFIO.  It's expected that
+   future IOMMU technologies will reduce some, but maybe not all, of
+   these trade-offs.
 
-[4] In this case the device is below a PCI bridge, so transactions
-from either function of the device are indistinguishable to the iommu:
+.. [4] In this case the device is below a PCI bridge, so transactions
+   from either function of the device are indistinguishable to the iommu::
 
--[0000:00]-+-1e.0-[06]--+-0d.0
-                        \-0d.1
+	-[0000:00]-+-1e.0-[06]--+-0d.0
+				\-0d.1
 
-00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 90)
+	00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 90)
-- 
2.9.4

[PATCH 25/29] video-output.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- mark the title;
- mark the authorship;
- mark literal block.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/video-output.txt | 54 +++++++++++++++++++++---------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt
index e517011be4f9..1f7d8cf7209b 100644
--- a/Documentation/video-output.txt
+++ b/Documentation/video-output.txt
@@ -1,34 +1,34 @@
+=============================
+Video Output Switcher Control
+=============================
 
-		Video Output Switcher Control
-		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-		2006 luming.yu@intel.com
+:Author: 2006 luming.yu@intel.com
 
 The output sysfs class driver provides an abstract video output layer that
 can be used to hook platform specific methods to enable/disable video output
 device through common sysfs interface. For example, on my IBM ThinkPad T42
 laptop, The ACPI video driver registered its output devices and read/write
-method for 'state' with output sysfs class. The user interface under sysfs is:
-
-linux:/sys/class/video_output # tree .
-.
-|-- CRT0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- DVI0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- LCD0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-`-- TV0
-   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-   |-- state
-   |-- subsystem -> ../../../class/video_output
-   `-- uevent
+method for 'state' with output sysfs class. The user interface under sysfs is::
 
+	linux:/sys/class/video_output # tree .
+	.
+	|-- CRT0
+	|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+	|   |-- state
+	|   |-- subsystem -> ../../../class/video_output
+	|   `-- uevent
+	|-- DVI0
+	|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+	|   |-- state
+	|   |-- subsystem -> ../../../class/video_output
+	|   `-- uevent
+	|-- LCD0
+	|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+	|   |-- state
+	|   |-- subsystem -> ../../../class/video_output
+	|   `-- uevent
+	`-- TV0
+	   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+	   |-- state
+	   |-- subsystem -> ../../../class/video_output
+	   `-- uevent
-- 
2.9.4

[PATCH 26/29] xillybus.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Adjust indentation;
- Mark authorship;
- Comment internal contents table;
- Mark literal blocks;
- Don't use all-upercase titles.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/xillybus.txt | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/Documentation/xillybus.txt b/Documentation/xillybus.txt
index 1660145b9969..2446ee303c09 100644
--- a/Documentation/xillybus.txt
+++ b/Documentation/xillybus.txt
@@ -1,12 +1,11 @@
+==========================================
+Xillybus driver for generic FPGA interface
+==========================================
 
-               ==========================================
-               Xillybus driver for generic FPGA interface
-               ==========================================
+:Author: Eli Billauer, Xillybus Ltd. (http://xillybus.com)
+:Email:  eli.billauer@gmail.com or as advertised on Xillybus' site.
 
-Author: Eli Billauer, Xillybus Ltd. (http://xillybus.com)
-Email:  eli.billauer@gmail.com or as advertised on Xillybus' site.
-
-Contents:
+.. Contents:
 
  - Introduction
   -- Background
@@ -17,7 +16,7 @@ Contents:
   -- Synchronization
   -- Seekable pipes
 
-- Internals
+ - Internals
   -- Source code organization
   -- Pipe attributes
   -- Host never reads from the FPGA
@@ -29,7 +28,7 @@ Contents:
   -- The "nonempty" message (supporting poll)
 
 
-INTRODUCTION
+Introduction
 ============
 
 Background
@@ -105,7 +104,7 @@ driver is used to work out of the box with any Xillybus IP core.
 The data structure just mentioned should not be confused with PCI's
 configuration space or the Flattened Device Tree.
 
-USAGE
+Usage
 =====
 
 User interface
@@ -117,11 +116,11 @@ names of these files depend on the IP core that is loaded in the FPGA (see
 Probing below). To communicate with the FPGA, open the device file that
 corresponds to the hardware FIFO you want to send data or receive data from,
 and use plain write() or read() calls, just like with a regular pipe. In
-particular, it makes perfect sense to go:
+particular, it makes perfect sense to go::
 
-$ cat mydata > /dev/xillybus_thisfifo
+	$ cat mydata > /dev/xillybus_thisfifo
 
-$ cat /dev/xillybus_thatfifo > hisdata
+	$ cat /dev/xillybus_thatfifo > hisdata
 
 possibly pressing CTRL-C as some stage, even though the xillybus_* pipes have
 the capability to send an EOF (but may not use it).
@@ -178,7 +177,7 @@ the attached memory is done by seeking to the desired address, and calling
 read() or write() as required.
 
 
-INTERNALS
+Internals
 =========
 
 Source code organization
@@ -365,7 +364,7 @@ into that page. It can be shown that all pages requested from the kernel
 (except possibly for the last) are 100% utilized this way.
 
 The "nonempty" message (supporting poll)
----------------------------------------
+----------------------------------------
 
 In order to support the "poll" method (and hence select() ), there is a small
 catch regarding the FPGA to host direction: The FPGA may have filled a DMA
-- 
2.9.4

[PATCH 27/29] xz.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use marks for titles;
- Adjust indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/xz.txt | 182 ++++++++++++++++++++++++++-------------------------
 1 file changed, 94 insertions(+), 88 deletions(-)

diff --git a/Documentation/xz.txt b/Documentation/xz.txt
index 2cf3e2608de3..b2220d03aa50 100644
--- a/Documentation/xz.txt
+++ b/Documentation/xz.txt
@@ -1,121 +1,127 @@
-
+============================
 XZ data compression in Linux
 ============================
 
 Introduction
+============
 
-    XZ is a general purpose data compression format with high compression
-    ratio and relatively fast decompression. The primary compression
-    algorithm (filter) is LZMA2. Additional filters can be used to improve
-    compression ratio even further. E.g. Branch/Call/Jump (BCJ) filters
-    improve compression ratio of executable data.
+XZ is a general purpose data compression format with high compression
+ratio and relatively fast decompression. The primary compression
+algorithm (filter) is LZMA2. Additional filters can be used to improve
+compression ratio even further. E.g. Branch/Call/Jump (BCJ) filters
+improve compression ratio of executable data.
 
-    The XZ decompressor in Linux is called XZ Embedded. It supports
-    the LZMA2 filter and optionally also BCJ filters. CRC32 is supported
-    for integrity checking. The home page of XZ Embedded is at
-    <http://tukaani.org/xz/embedded.html>, where you can find the
-    latest version and also information about using the code outside
-    the Linux kernel.
+The XZ decompressor in Linux is called XZ Embedded. It supports
+the LZMA2 filter and optionally also BCJ filters. CRC32 is supported
+for integrity checking. The home page of XZ Embedded is at
+<http://tukaani.org/xz/embedded.html>, where you can find the
+latest version and also information about using the code outside
+the Linux kernel.
 
-    For userspace, XZ Utils provide a zlib-like compression library
-    and a gzip-like command line tool. XZ Utils can be downloaded from
-    <http://tukaani.org/xz/>.
+For userspace, XZ Utils provide a zlib-like compression library
+and a gzip-like command line tool. XZ Utils can be downloaded from
+<http://tukaani.org/xz/>.
 
 XZ related components in the kernel
+===================================
 
-    The xz_dec module provides XZ decompressor with single-call (buffer
-    to buffer) and multi-call (stateful) APIs. The usage of the xz_dec
-    module is documented in include/linux/xz.h.
+The xz_dec module provides XZ decompressor with single-call (buffer
+to buffer) and multi-call (stateful) APIs. The usage of the xz_dec
+module is documented in include/linux/xz.h.
 
-    The xz_dec_test module is for testing xz_dec. xz_dec_test is not
-    useful unless you are hacking the XZ decompressor. xz_dec_test
-    allocates a char device major dynamically to which one can write
-    .xz files from userspace. The decompressed output is thrown away.
-    Keep an eye on dmesg to see diagnostics printed by xz_dec_test.
-    See the xz_dec_test source code for the details.
+The xz_dec_test module is for testing xz_dec. xz_dec_test is not
+useful unless you are hacking the XZ decompressor. xz_dec_test
+allocates a char device major dynamically to which one can write
+.xz files from userspace. The decompressed output is thrown away.
+Keep an eye on dmesg to see diagnostics printed by xz_dec_test.
+See the xz_dec_test source code for the details.
 
-    For decompressing the kernel image, initramfs, and initrd, there
-    is a wrapper function in lib/decompress_unxz.c. Its API is the
-    same as in other decompress_*.c files, which is defined in
-    include/linux/decompress/generic.h.
+For decompressing the kernel image, initramfs, and initrd, there
+is a wrapper function in lib/decompress_unxz.c. Its API is the
+same as in other decompress_*.c files, which is defined in
+include/linux/decompress/generic.h.
 
-    scripts/xz_wrap.sh is a wrapper for the xz command line tool found
-    from XZ Utils. The wrapper sets compression options to values suitable
-    for compressing the kernel image.
+scripts/xz_wrap.sh is a wrapper for the xz command line tool found
+from XZ Utils. The wrapper sets compression options to values suitable
+for compressing the kernel image.
 
-    For kernel makefiles, two commands are provided for use with
-    $(call if_needed). The kernel image should be compressed with
-    $(call if_needed,xzkern) which will use a BCJ filter and a big LZMA2
-    dictionary. It will also append a four-byte trailer containing the
-    uncompressed size of the file, which is needed by the boot code.
-    Other things should be compressed with $(call if_needed,xzmisc)
-    which will use no BCJ filter and 1 MiB LZMA2 dictionary.
+For kernel makefiles, two commands are provided for use with
+$(call if_needed). The kernel image should be compressed with
+$(call if_needed,xzkern) which will use a BCJ filter and a big LZMA2
+dictionary. It will also append a four-byte trailer containing the
+uncompressed size of the file, which is needed by the boot code.
+Other things should be compressed with $(call if_needed,xzmisc)
+which will use no BCJ filter and 1 MiB LZMA2 dictionary.
 
 Notes on compression options
+============================
 
-    Since the XZ Embedded supports only streams with no integrity check or
-    CRC32, make sure that you don't use some other integrity check type
-    when encoding files that are supposed to be decoded by the kernel. With
-    liblzma, you need to use either LZMA_CHECK_NONE or LZMA_CHECK_CRC32
-    when encoding. With the xz command line tool, use --check=none or
-    --check=crc32.
+Since the XZ Embedded supports only streams with no integrity check or
+CRC32, make sure that you don't use some other integrity check type
+when encoding files that are supposed to be decoded by the kernel. With
+liblzma, you need to use either LZMA_CHECK_NONE or LZMA_CHECK_CRC32
+when encoding. With the xz command line tool, use --check=none or
+--check=crc32.
 
-    Using CRC32 is strongly recommended unless there is some other layer
-    which will verify the integrity of the uncompressed data anyway.
-    Double checking the integrity would probably be waste of CPU cycles.
-    Note that the headers will always have a CRC32 which will be validated
-    by the decoder; you can only change the integrity check type (or
-    disable it) for the actual uncompressed data.
+Using CRC32 is strongly recommended unless there is some other layer
+which will verify the integrity of the uncompressed data anyway.
+Double checking the integrity would probably be waste of CPU cycles.
+Note that the headers will always have a CRC32 which will be validated
+by the decoder; you can only change the integrity check type (or
+disable it) for the actual uncompressed data.
 
-    In userspace, LZMA2 is typically used with dictionary sizes of several
-    megabytes. The decoder needs to have the dictionary in RAM, thus big
-    dictionaries cannot be used for files that are intended to be decoded
-    by the kernel. 1 MiB is probably the maximum reasonable dictionary
-    size for in-kernel use (maybe more is OK for initramfs). The presets
-    in XZ Utils may not be optimal when creating files for the kernel,
-    so don't hesitate to use custom settings. Example:
+In userspace, LZMA2 is typically used with dictionary sizes of several
+megabytes. The decoder needs to have the dictionary in RAM, thus big
+dictionaries cannot be used for files that are intended to be decoded
+by the kernel. 1 MiB is probably the maximum reasonable dictionary
+size for in-kernel use (maybe more is OK for initramfs). The presets
+in XZ Utils may not be optimal when creating files for the kernel,
+so don't hesitate to use custom settings. Example::
 
-        xz --check=crc32 --lzma2=dict=512KiB inputfile
+	xz --check=crc32 --lzma2=dict=512KiB inputfile
 
-    An exception to above dictionary size limitation is when the decoder
-    is used in single-call mode. Decompressing the kernel itself is an
-    example of this situation. In single-call mode, the memory usage
-    doesn't depend on the dictionary size, and it is perfectly fine to
-    use a big dictionary: for maximum compression, the dictionary should
-    be at least as big as the uncompressed data itself.
+An exception to above dictionary size limitation is when the decoder
+is used in single-call mode. Decompressing the kernel itself is an
+example of this situation. In single-call mode, the memory usage
+doesn't depend on the dictionary size, and it is perfectly fine to
+use a big dictionary: for maximum compression, the dictionary should
+be at least as big as the uncompressed data itself.
 
 Future plans
+============
 
-    Creating a limited XZ encoder may be considered if people think it is
-    useful. LZMA2 is slower to compress than e.g. Deflate or LZO even at
-    the fastest settings, so it isn't clear if LZMA2 encoder is wanted
-    into the kernel.
+Creating a limited XZ encoder may be considered if people think it is
+useful. LZMA2 is slower to compress than e.g. Deflate or LZO even at
+the fastest settings, so it isn't clear if LZMA2 encoder is wanted
+into the kernel.
 
-    Support for limited random-access reading is planned for the
-    decompression code. I don't know if it could have any use in the
-    kernel, but I know that it would be useful in some embedded projects
-    outside the Linux kernel.
+Support for limited random-access reading is planned for the
+decompression code. I don't know if it could have any use in the
+kernel, but I know that it would be useful in some embedded projects
+outside the Linux kernel.
 
 Conformance to the .xz file format specification
+================================================
 
-    There are a couple of corner cases where things have been simplified
-    at expense of detecting errors as early as possible. These should not
-    matter in practice all, since they don't cause security issues. But
-    it is good to know this if testing the code e.g. with the test files
-    from XZ Utils.
+There are a couple of corner cases where things have been simplified
+at expense of detecting errors as early as possible. These should not
+matter in practice all, since they don't cause security issues. But
+it is good to know this if testing the code e.g. with the test files
+from XZ Utils.
 
 Reporting bugs
+==============
 
-    Before reporting a bug, please check that it's not fixed already
-    at upstream. See <http://tukaani.org/xz/embedded.html> to get the
-    latest code.
+Before reporting a bug, please check that it's not fixed already
+at upstream. See <http://tukaani.org/xz/embedded.html> to get the
+latest code.
 
-    Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on
-    Freenode and talk to Larhzu. I don't actively read LKML or other
-    kernel-related mailing lists, so if there's something I should know,
-    you should email to me personally or use IRC.
+Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on
+Freenode and talk to Larhzu. I don't actively read LKML or other
+kernel-related mailing lists, so if there's something I should know,
+you should email to me personally or use IRC.
 
-    Don't bother Igor Pavlov with questions about the XZ implementation
-    in the kernel or about XZ Utils. While these two implementations
-    include essential code that is directly based on Igor Pavlov's code,
-    these implementations aren't maintained nor supported by him.
+Don't bother Igor Pavlov with questions about the XZ implementation
+in the kernel or about XZ Utils. While these two implementations
+include essential code that is directly based on Igor Pavlov's code,
+these implementations aren't maintained nor supported by him.
-- 
2.9.4

[PATCH 28/29] zorro.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Use right marks for titles;
- Use authorship marks;
- Mark literals and literal blocks;
- Use autonumbered list for references.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/zorro.txt | 59 +++++++++++++++++++++++++------------------------
 1 file changed, 30 insertions(+), 29 deletions(-)

diff --git a/Documentation/zorro.txt b/Documentation/zorro.txt
index d530971beb00..664072b017e3 100644
--- a/Documentation/zorro.txt
+++ b/Documentation/zorro.txt
@@ -1,12 +1,13 @@
-		Writing Device Drivers for Zorro Devices
-		----------------------------------------
+========================================
+Writing Device Drivers for Zorro Devices
+========================================
 
-Written by Geert Uytterhoeven <geert@linux-m68k.org>
-Last revised: September 5, 2003
+:Author: Written by Geert Uytterhoeven <geert@linux-m68k.org>
+:Last revised: September 5, 2003
 
 
-1. Introduction
----------------
+Introduction
+------------
 
 The Zorro bus is the bus used in the Amiga family of computers. Thanks to
 AutoConfig(tm), it's 100% Plug-and-Play.
@@ -20,12 +21,12 @@ There are two types of Zorro buses, Zorro II and Zorro III:
     with Zorro II. The Zorro III address space lies outside the first 16 MB.
 
 
-2. Probing for Zorro Devices
-----------------------------
+Probing for Zorro Devices
+-------------------------
 
-Zorro devices are found by calling `zorro_find_device()', which returns a
-pointer to the `next' Zorro device with the specified Zorro ID. A probe loop
-for the board with Zorro ID `ZORRO_PROD_xxx' looks like:
+Zorro devices are found by calling ``zorro_find_device()``, which returns a
+pointer to the ``next`` Zorro device with the specified Zorro ID. A probe loop
+for the board with Zorro ID ``ZORRO_PROD_xxx`` looks like::
 
     struct zorro_dev *z = NULL;
 
@@ -35,8 +36,8 @@ for the board with Zorro ID `ZORRO_PROD_xxx' looks like:
 	...
     }
 
-`ZORRO_WILDCARD' acts as a wildcard and finds any Zorro device. If your driver
-supports different types of boards, you can use a construct like:
+``ZORRO_WILDCARD`` acts as a wildcard and finds any Zorro device. If your driver
+supports different types of boards, you can use a construct like::
 
     struct zorro_dev *z = NULL;
 
@@ -49,24 +50,24 @@ supports different types of boards, you can use a construct like:
     }
 
 
-3. Zorro Resources
-------------------
+Zorro Resources
+---------------
 
 Before you can access a Zorro device's registers, you have to make sure it's
 not yet in use. This is done using the I/O memory space resource management
-functions:
+functions::
 
     request_mem_region()
     release_mem_region()
 
-Shortcuts to claim the whole device's address space are provided as well:
+Shortcuts to claim the whole device's address space are provided as well::
 
     zorro_request_device
     zorro_release_device
 
 
-4. Accessing the Zorro Address Space
-------------------------------------
+Accessing the Zorro Address Space
+---------------------------------
 
 The address regions in the Zorro device resources are Zorro bus address
 regions. Due to the identity bus-physical address mapping on the Zorro bus,
@@ -78,26 +79,26 @@ The treatment of these regions depends on the type of Zorro space:
     explicitly using z_ioremap().
     
     Conversion from bus/physical Zorro II addresses to kernel virtual addresses
-    and vice versa is done using:
+    and vice versa is done using::
 
 	virt_addr = ZTWO_VADDR(bus_addr);
 	bus_addr = ZTWO_PADDR(virt_addr);
 
   - Zorro III address space must be mapped explicitly using z_ioremap() first
-    before it can be accessed:
+    before it can be accessed::
  
 	virt_addr = z_ioremap(bus_addr, size);
 	...
 	z_iounmap(virt_addr);
 
 
-5. References
--------------
+References
+----------
 
-linux/include/linux/zorro.h
-linux/include/uapi/linux/zorro.h
-linux/include/uapi/linux/zorro_ids.h
-linux/arch/m68k/include/asm/zorro.h
-linux/drivers/zorro
-/proc/bus/zorro
+#. linux/include/linux/zorro.h
+#. linux/include/uapi/linux/zorro.h
+#. linux/include/uapi/linux/zorro_ids.h
+#. linux/arch/m68k/include/asm/zorro.h
+#. linux/drivers/zorro
+#. /proc/bus/zorro
 
-- 
2.9.4

[PATCH 29/29] dell_rbu.txt: standardize document format

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx.

Currently, the document is completely unformatted. Add
titles, do indentation, mark literal blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/dell_rbu.txt | 81 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 56 insertions(+), 25 deletions(-)

diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.txt
index d262e22bddec..0fdb6aa2704c 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.txt
@@ -1,18 +1,30 @@
-Purpose:
-Demonstrate the usage of the new open sourced rbu (Remote BIOS Update) driver
+=============================================================
+Usage of the new open sourced rbu (Remote BIOS Update) driver
+=============================================================
+
+Purpose
+=======
+
+Document demonstrating the use of the Dell Remote BIOS Update driver.
 for updating BIOS images on Dell servers and desktops.
 
-Scope:
+Scope
+=====
+
 This document discusses the functionality of the rbu driver only.
 It does not cover the support needed from applications to enable the BIOS to
 update itself with the image downloaded in to the memory.
 
-Overview:
+Overview
+========
+
 This driver works with Dell OpenManage or Dell Update Packages for updating
 the BIOS on Dell servers (starting from servers sold since 1999), desktops
 and notebooks (starting from those sold in 2005).
+
 Please go to  http://support.dell.com register and you can find info on
 OpenManage and Dell Update packages (DUP).
+
 Libsmbios can also be used to update BIOS on Dell systems go to
 http://linux.dell.com/libsmbios/ for details.
 
@@ -22,6 +34,7 @@ of physical pages having the BIOS image. In case of packetized the app
 using the driver breaks the image in to packets of fixed sizes and the driver
 would place each packet in contiguous physical memory. The driver also
 maintains a link list of packets for reading them back.
+
 If the dell_rbu driver is unloaded all the allocated memory is freed.
 
 The rbu driver needs to have an application (as mentioned above)which will
@@ -30,28 +43,33 @@ inform the BIOS to enable the update in the next system reboot.
 The user should not unload the rbu driver after downloading the BIOS image
 or updating.
 
-The driver load creates the following directories under the /sys file system.
-/sys/class/firmware/dell_rbu/loading
-/sys/class/firmware/dell_rbu/data
-/sys/devices/platform/dell_rbu/image_type
-/sys/devices/platform/dell_rbu/data
-/sys/devices/platform/dell_rbu/packet_size
+The driver load creates the following directories under the /sys file system::
+
+	/sys/class/firmware/dell_rbu/loading
+	/sys/class/firmware/dell_rbu/data
+	/sys/devices/platform/dell_rbu/image_type
+	/sys/devices/platform/dell_rbu/data
+	/sys/devices/platform/dell_rbu/packet_size
 
 The driver supports two types of update mechanism; monolithic and packetized.
 These update mechanism depends upon the BIOS currently running on the system.
 Most of the Dell systems support a monolithic update where the BIOS image is
 copied to a single contiguous block of physical memory.
+
 In case of packet mechanism the single memory can be broken in smaller chunks
 of contiguous memory and the BIOS image is scattered in these packets.
 
 By default the driver uses monolithic memory for the update type. This can be
 changed to packets during the driver load time by specifying the load
-parameter image_type=packet.  This can also be changed later as below
-echo packet > /sys/devices/platform/dell_rbu/image_type
+parameter image_type=packet.  This can also be changed later as below::
+
+	echo packet > /sys/devices/platform/dell_rbu/image_type
 
 In packet update mode the packet size has to be given before any packets can
-be downloaded. It is done as below
-echo XXXX > /sys/devices/platform/dell_rbu/packet_size
+be downloaded. It is done as below::
+
+	echo XXXX > /sys/devices/platform/dell_rbu/packet_size
+
 In the packet update mechanism, the user needs to create a new file having
 packets of data arranged back to back. It can be done as follows
 The user creates packets header, gets the chunk of the BIOS image and
@@ -60,41 +78,54 @@ added together should match the specified packet_size. This makes one
 packet, the user needs to create more such packets out of the entire BIOS
 image file and then arrange all these packets back to back in to one single
 file.
+
 This file is then copied to /sys/class/firmware/dell_rbu/data.
 Once this file gets to the driver, the driver extracts packet_size data from
 the file and spreads it across the physical memory in contiguous packet_sized
 space.
+
 This method makes sure that all the packets get to the driver in a single operation.
 
 In monolithic update the user simply get the BIOS image (.hdr file) and copies
 to the data file as is without any change to the BIOS image itself.
 
 Do the steps below to download the BIOS image.
+
 1) echo 1 > /sys/class/firmware/dell_rbu/loading
 2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data
 3) echo 0 > /sys/class/firmware/dell_rbu/loading
 
 The /sys/class/firmware/dell_rbu/ entries will remain till the following is
 done.
-echo -1 > /sys/class/firmware/dell_rbu/loading
+
+::
+
+	echo -1 > /sys/class/firmware/dell_rbu/loading
+
 Until this step is completed the driver cannot be unloaded.
+
 Also echoing either mono, packet or init in to image_type will free up the
 memory allocated by the driver.
 
 If a user by accident executes steps 1 and 3 above without executing step 2;
 it will make the /sys/class/firmware/dell_rbu/ entries disappear.
-The entries can be recreated by doing the following
-echo init > /sys/devices/platform/dell_rbu/image_type
-NOTE: echoing init in image_type does not change it original value.
+
+The entries can be recreated by doing the following::
+
+	echo init > /sys/devices/platform/dell_rbu/image_type
+
+.. note:: echoing init in image_type does not change it original value.
 
 Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to
 read back the image downloaded.
 
-NOTE:
-This driver requires a patch for firmware_class.c which has the modified
-request_firmware_nowait function.
-Also after updating the BIOS image a user mode application needs to execute
-code which sends the BIOS update request to the BIOS. So on the next reboot
-the BIOS knows about the new image downloaded and it updates itself.
-Also don't unload the rbu driver if the image has to be updated.
+.. note::
+
+   This driver requires a patch for firmware_class.c which has the modified
+   request_firmware_nowait function.
+
+   Also after updating the BIOS image a user mode application needs to execute
+   code which sends the BIOS update request to the BIOS. So on the next reboot
+   the BIOS knows about the new image downloaded and it updates itself.
+   Also don't unload the rbu driver if the image has to be updated.
 
-- 
2.9.4

Re: [PATCH 08/29] rfkill.txt: standardize document format

[Johannes Berg]

On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> 
> +.. CONTENTS
>  
> +  1. Introduction
> +  2. Implementation details
> +  3. Kernel API
> +  4. Userspace support

Why not let this be auto-generated?

.. contents::
   :depth: 1

should work, no?

johannes

Re: [PATCH 04/29] printk-formats.txt: standardize document format

[Joe Perches]

On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
> 
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> 
> - add a title for the document;
> - add markups for section titles;
> - move authorship to the beginning and use :Author:;
> - use right markup for tables;
> - mark literals and literal blocks.

I think the .rst markup is far uglier to read as text
and harder to modify for new additions to %p<foo>
given column alignments.

For instance below, but other than that, the .rst
is easier to read.

> diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
[]
> @@ -1,139 +1,180 @@
> -If variable is of Type,		use printk format specifier:
> ----------------------------------------------------------
> -		int			%d or %x
> -		unsigned int		%u or %x
> -		long			%ld or %lx
> -		unsigned long		%lu or %lx
> -		long long		%lld or %llx
> -		unsigned long long	%llu or %llx
> -		size_t			%zu or %zx
> -		ssize_t			%zd or %zx
> -		s32			%d or %x
> -		u32			%u or %x
> -		s64			%lld or %llx
> -		u64			%llu or %llx
[]
> +======================= ===========================
> +If variable is of Type	use printk format specifier
> +======================= ===========================
> +``int``			``%d or %x``
> +``unsigned int``	``%u or %x``
> +``long``		``%ld or %lx``
> +``unsigned long``	``%lu or %lx``
> +``long long``		``%lld or %llx``
> +``unsigned long long``	``%llu or %llx``
> +``size_t``		``%zu or %zx``
> +``ssize_t``		``%zd or %zx``
> +``s32``			``%d or %x``
> +``u32``			``%u or %x``
> +``s64``			``%lld or %llx``
> +``u64``			``%llu or %llx``
> +======================= ===========================

Re: [PATCH 08/29] rfkill.txt: standardize document format

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 12:15:01 +0200
Johannes Berg <johannes@sipsolutions.net> escreveu:

> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> > 
> > +.. CONTENTS
> >  
> > +  1. Introduction
> > +  2. Implementation details
> > +  3. Kernel API
> > +  4. Userspace support  
> 
> Why not let this be auto-generated?
> 
> .. contents::
>    :depth: 1
> 
> should work, no?

Yes, it should work. Actually, you would need to use :depth: 2 to
produce this output:


	Contents

	    . rfkill - RF kill switch support
	        . Introduction
	        . Implementation details
	        . Kernel API
	        . Userspace support

I opted to keep the contents as a comment just because, in the past, some
maintainers complained about TOC removal, arguing that it makes harder
for the ones that would be reading the file in ascii.

Thanks,
Mauro

Re: [PATCH 08/29] rfkill.txt: standardize document format

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 12:15:01 +0200
Johannes Berg <johannes@sipsolutions.net> escreveu:

> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> > 
> > +.. CONTENTS
> >  
> > +  1. Introduction
> > +  2. Implementation details
> > +  3. Kernel API
> > +  4. Userspace support  
> 
> Why not let this be auto-generated?
> 
> .. contents::
>    :depth: 1
> 
> should work, no?

Yes, it should work. Actually, you would need to use :depth: 2 to
produce this output:


	Contents

	    . rfkill - RF kill switch support
	        . Introduction
	        . Implementation details
	        . Kernel API
	        . Userspace support

I opted to keep the contents as a comment just because, in the past, some
maintainers complained about TOC removal, arguing that it makes harder
for the ones that would be reading the file in ascii.

Thanks,
Mauro

Re: [PATCH 08/29] rfkill.txt: standardize document format

[Johannes Berg]

On Fri, 2017-05-19 at 08:11 -0300, Mauro Carvalho Chehab wrote:
> 
> Yes, it should work. Actually, you would need to use :depth: 2 to
> produce this output:
> 
> 
> 	Contents
> 
> 	    . rfkill - RF kill switch support
> 	        . Introduction
> 	        . Implementation details
> 	        . Kernel API
> 	        . Userspace support

Sounds good to me.

> I opted to keep the contents as a comment just because, in the past,
> some maintainers complained about TOC removal, arguing that it makes
> harder for the ones that would be reading the file in ascii.

Ok. I don't really care much either way, I guess. The file is short
enough that the TOC isn't all that important to start with.

johannes

Re: [PATCH 08/29] rfkill.txt: standardize document format

[Johannes Berg]

On Fri, 2017-05-19 at 08:11 -0300, Mauro Carvalho Chehab wrote:
> 
> Yes, it should work. Actually, you would need to use :depth: 2 to
> produce this output:
> 
> 
> 	Contents
> 
> 	    . rfkill - RF kill switch support
> 	        . Introduction
> 	        . Implementation details
> 	        . Kernel API
> 	        . Userspace support

Sounds good to me.

> I opted to keep the contents as a comment just because, in the past,
> some maintainers complained about TOC removal, arguing that it makes
> harder for the ones that would be reading the file in ascii.

Ok. I don't really care much either way, I guess. The file is short
enough that the TOC isn't all that important to start with.

johannes

Re: [PATCH 19/29] svga.txt: standardize document format

[Martin Mares]

> diff --git a/Documentation/svga.txt b/Documentation/svga.txt
> index cd66ec836e4f..119f1515b1ac 100644
> --- a/Documentation/svga.txt
> +++ b/Documentation/svga.txt
> @@ -1,24 +1,31 @@

Acked-By: Martin Mares <mj@ucw.cz>

				Have a nice fortnight
-- 
Martin `MJ' Mares                          <mj@ucw.cz>   http://mj.ucw.cz/
Faculty of Math and Physics, Charles University, Prague, Czech Rep., Earth
Press any key to quit or any other key to continue

Re: [PATCH 04/29] printk-formats.txt: standardize document format

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 03:26:08 -0700
Joe Perches <joe@perches.com> escreveu:

> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> > 
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx:
> > 
> > - add a title for the document;
> > - add markups for section titles;
> > - move authorship to the beginning and use :Author:;
> > - use right markup for tables;
> > - mark literals and literal blocks.  
> 
> I think the .rst markup is far uglier to read as text
> and harder to modify for new additions to %p<foo>
> given column alignments.
> 
> For instance below, but other than that, the .rst
> is easier to read.
> 
> > diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt  
> []
> > @@ -1,139 +1,180 @@
> > -If variable is of Type,		use printk format specifier:
> > ----------------------------------------------------------
> > -		int			%d or %x
> > -		unsigned int		%u or %x
> > -		long			%ld or %lx
> > -		unsigned long		%lu or %lx
> > -		long long		%lld or %llx
> > -		unsigned long long	%llu or %llx
> > -		size_t			%zu or %zx
> > -		ssize_t			%zd or %zx
> > -		s32			%d or %x
> > -		u32			%u or %x
> > -		s64			%lld or %llx
> > -		u64			%llu or %llx  
> []
> > +======================= ===========================
> > +If variable is of Type	use printk format specifier
> > +======================= ===========================
> > +``int``			``%d or %x``
> > +``unsigned int``	``%u or %x``
> > +``long``		``%ld or %lx``
> > +``unsigned long``	``%lu or %lx``
> > +``long long``		``%lld or %llx``
> > +``unsigned long long``	``%llu or %llx``
> > +``size_t``		``%zu or %zx``
> > +``ssize_t``		``%zd or %zx``
> > +``s32``			``%d or %x``
> > +``u32``			``%u or %x``
> > +``s64``			``%lld or %llx``
> > +``u64``			``%llu or %llx``
> > +======================= ===========================  

Well, we could,instead, use literal blocks, e. g. something like:

::

 -If variable is of Type,		use printk format specifier:
 ----------------------------------------------------------
 -		int			%d or %x
 -		unsigned int		%u or %x
 -		long			%ld or %lx
 -		unsigned long		%lu or %lx
 -		long long		%lld or %llx
 -		unsigned long long	%llu or %llx
 -		size_t			%zu or %zx
 -		ssize_t			%zd or %zx
 -		s32			%d or %x
 -		u32			%u or %x
 -		s64			%lld or %llx
 -		u64			%llu or %llx  



Cheers,
Mauro

Re: [PATCH 04/29] printk-formats.txt: standardize document format

[Randy Dunlap]

On 05/19/17 13:28, Mauro Carvalho Chehab wrote:
> Em Fri, 19 May 2017 03:26:08 -0700
> Joe Perches <joe@perches.com> escreveu:
> 
>> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
>>> Each text file under Documentation follows a different
>>> format. Some doesn't even have titles!
>>>
>>> Change its representation to follow the adopted standard,
>>> using ReST markups for it to be parseable by Sphinx:
>>>
>>> - add a title for the document;
>>> - add markups for section titles;
>>> - move authorship to the beginning and use :Author:;
>>> - use right markup for tables;
>>> - mark literals and literal blocks.  
>>
>> I think the .rst markup is far uglier to read as text
>> and harder to modify for new additions to %p<foo>
>> given column alignments.
>>
>> For instance below, but other than that, the .rst
>> is easier to read.
>>
>>> diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt  
>> []
>>> @@ -1,139 +1,180 @@
>>> -If variable is of Type,		use printk format specifier:
>>> ----------------------------------------------------------
>>> -		int			%d or %x
>>> -		unsigned int		%u or %x
>>> -		long			%ld or %lx
>>> -		unsigned long		%lu or %lx
>>> -		long long		%lld or %llx
>>> -		unsigned long long	%llu or %llx
>>> -		size_t			%zu or %zx
>>> -		ssize_t			%zd or %zx
>>> -		s32			%d or %x
>>> -		u32			%u or %x
>>> -		s64			%lld or %llx
>>> -		u64			%llu or %llx  
>> []
>>> +======================= ===========================
>>> +If variable is of Type	use printk format specifier
>>> +======================= ===========================
>>> +``int``			``%d or %x``
>>> +``unsigned int``	``%u or %x``
>>> +``long``		``%ld or %lx``
>>> +``unsigned long``	``%lu or %lx``
>>> +``long long``		``%lld or %llx``
>>> +``unsigned long long``	``%llu or %llx``
>>> +``size_t``		``%zu or %zx``
>>> +``ssize_t``		``%zd or %zx``
>>> +``s32``			``%d or %x``
>>> +``u32``			``%u or %x``
>>> +``s64``			``%lld or %llx``
>>> +``u64``			``%llu or %llx``
>>> +======================= ===========================  
> 
> Well, we could,instead, use literal blocks, e. g. something like:
> 
> ::
> 
>  -If variable is of Type,		use printk format specifier:
>  ----------------------------------------------------------
>  -		int			%d or %x
>  -		unsigned int		%u or %x
>  -		long			%ld or %lx
>  -		unsigned long		%lu or %lx
>  -		long long		%lld or %llx
>  -		unsigned long long	%llu or %llx
>  -		size_t			%zu or %zx
>  -		ssize_t			%zd or %zx
>  -		s32			%d or %x
>  -		u32			%u or %x
>  -		s64			%lld or %llx
>  -		u64			%llu or %llx  
> 

I like that latter option.

thanks.
-- 
~Randy

Re: [PATCH 23/29] vfio-mediated-device.txt: standardize document format

[Kirti Wankhede]

On 5/19/2017 6:56 AM, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
> 
> In this specific document, the title, copyright and authorship
> are added as if it were a C file!
> 
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> - convert document preambule to the proper format;
> - mark literal blocks;
> - adjust identation;
> - use numbered lists for references.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Looks good to me.

Reviewed by: Kirti Wankhede <kwankhede@nvidia.com>

Thanks,
Kirti

> ---
>  Documentation/vfio-mediated-device.txt | 252 +++++++++++++++++----------------
>  1 file changed, 130 insertions(+), 122 deletions(-)
> 
> diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> index e5e57b40f8af..1b3950346532 100644
> --- a/Documentation/vfio-mediated-device.txt
> +++ b/Documentation/vfio-mediated-device.txt
> @@ -1,14 +1,17 @@
> -/*
> - * VFIO Mediated devices
> - *
> - * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
> - *     Author: Neo Jia <cjia@nvidia.com>
> - *             Kirti Wankhede <kwankhede@nvidia.com>
> - *
> - * This program is free software; you can redistribute it and/or modify
> - * it under the terms of the GNU General Public License version 2 as
> - * published by the Free Software Foundation.
> - */
> +.. include:: <isonum.txt>
> +
> +=====================
> +VFIO Mediated devices
> +=====================
> +
> +:Copyright: |copy| 2016, NVIDIA CORPORATION. All rights reserved.
> +:Author: Neo Jia <cjia@nvidia.com>
> +:Author: Kirti Wankhede <kwankhede@nvidia.com>
> +
> +This program is free software; you can redistribute it and/or modify
> +it under the terms of the GNU General Public License version 2 as
> +published by the Free Software Foundation.
> +
>  
>  Virtual Function I/O (VFIO) Mediated devices[1]
>  ===============================================
> @@ -42,7 +45,7 @@ removes it from a VFIO group.
>  
>  The following high-level block diagram shows the main components and interfaces
>  in the VFIO mediated driver framework. The diagram shows NVIDIA, Intel, and IBM
> -devices as examples, as these devices are the first devices to use this module.
> +devices as examples, as these devices are the first devices to use this module::
>  
>       +---------------+
>       |               |
> @@ -91,7 +94,7 @@ Registration Interface for a Mediated Bus Driver
>  ------------------------------------------------
>  
>  The registration interface for a mediated bus driver provides the following
> -structure to represent a mediated device's driver:
> +structure to represent a mediated device's driver::
>  
>       /*
>        * struct mdev_driver [2] - Mediated device's driver
> @@ -110,14 +113,14 @@ structure to represent a mediated device's driver:
>  A mediated bus driver for mdev should use this structure in the function calls
>  to register and unregister itself with the core driver:
>  
> -* Register:
> +* Register::
>  
> -  extern int  mdev_register_driver(struct mdev_driver *drv,
> +    extern int  mdev_register_driver(struct mdev_driver *drv,
>  				   struct module *owner);
>  
> -* Unregister:
> +* Unregister::
>  
> -  extern void mdev_unregister_driver(struct mdev_driver *drv);
> +    extern void mdev_unregister_driver(struct mdev_driver *drv);
>  
>  The mediated bus driver is responsible for adding mediated devices to the VFIO
>  group when devices are bound to the driver and removing mediated devices from
> @@ -152,15 +155,15 @@ The callbacks in the mdev_parent_ops structure are as follows:
>  * mmap: mmap emulation callback
>  
>  A driver should use the mdev_parent_ops structure in the function call to
> -register itself with the mdev core driver:
> +register itself with the mdev core driver::
>  
> -extern int  mdev_register_device(struct device *dev,
> -                                 const struct mdev_parent_ops *ops);
> +	extern int  mdev_register_device(struct device *dev,
> +	                                 const struct mdev_parent_ops *ops);
>  
>  However, the mdev_parent_ops structure is not required in the function call
> -that a driver should use to unregister itself with the mdev core driver:
> +that a driver should use to unregister itself with the mdev core driver::
>  
> -extern void mdev_unregister_device(struct device *dev);
> +	extern void mdev_unregister_device(struct device *dev);
>  
>  
>  Mediated Device Management Interface Through sysfs
> @@ -183,30 +186,32 @@ with the mdev core driver.
>  Directories and files under the sysfs for Each Physical Device
>  --------------------------------------------------------------
>  
> -|- [parent physical device]
> -|--- Vendor-specific-attributes [optional]
> -|--- [mdev_supported_types]
> -|     |--- [<type-id>]
> -|     |   |--- create
> -|     |   |--- name
> -|     |   |--- available_instances
> -|     |   |--- device_api
> -|     |   |--- description
> -|     |   |--- [devices]
> -|     |--- [<type-id>]
> -|     |   |--- create
> -|     |   |--- name
> -|     |   |--- available_instances
> -|     |   |--- device_api
> -|     |   |--- description
> -|     |   |--- [devices]
> -|     |--- [<type-id>]
> -|          |--- create
> -|          |--- name
> -|          |--- available_instances
> -|          |--- device_api
> -|          |--- description
> -|          |--- [devices]
> +::
> +
> +  |- [parent physical device]
> +  |--- Vendor-specific-attributes [optional]
> +  |--- [mdev_supported_types]
> +  |     |--- [<type-id>]
> +  |     |   |--- create
> +  |     |   |--- name
> +  |     |   |--- available_instances
> +  |     |   |--- device_api
> +  |     |   |--- description
> +  |     |   |--- [devices]
> +  |     |--- [<type-id>]
> +  |     |   |--- create
> +  |     |   |--- name
> +  |     |   |--- available_instances
> +  |     |   |--- device_api
> +  |     |   |--- description
> +  |     |   |--- [devices]
> +  |     |--- [<type-id>]
> +  |          |--- create
> +  |          |--- name
> +  |          |--- available_instances
> +  |          |--- device_api
> +  |          |--- description
> +  |          |--- [devices]
>  
>  * [mdev_supported_types]
>  
> @@ -219,12 +224,12 @@ Directories and files under the sysfs for Each Physical Device
>  
>    The [<type-id>] name is created by adding the device driver string as a prefix
>    to the string provided by the vendor driver. This format of this name is as
> -  follows:
> +  follows::
>  
>  	sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name);
>  
>    (or using mdev_parent_dev(mdev) to arrive at the parent device outside
> -   of the core mdev code)
> +  of the core mdev code)
>  
>  * device_api
>  
> @@ -239,7 +244,7 @@ Directories and files under the sysfs for Each Physical Device
>  * [device]
>  
>    This directory contains links to the devices of type <type-id> that have been
> -created.
> +  created.
>  
>  * name
>  
> @@ -253,21 +258,25 @@ created.
>  Directories and Files Under the sysfs for Each mdev Device
>  ----------------------------------------------------------
>  
> -|- [parent phy device]
> -|--- [$MDEV_UUID]
> +::
> +
> +  |- [parent phy device]
> +  |--- [$MDEV_UUID]
>           |--- remove
>           |--- mdev_type {link to its type}
>           |--- vendor-specific-attributes [optional]
>  
>  * remove (write only)
> +
>  Writing '1' to the 'remove' file destroys the mdev device. The vendor driver can
>  fail the remove() callback if that device is active and the vendor driver
>  doesn't support hot unplug.
>  
> -Example:
> +Example::
> +
>  	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
>  
> -Mediated device Hot plug:
> +Mediated device Hot plug
>  ------------------------
>  
>  Mediated devices can be created and assigned at runtime. The procedure to hot
> @@ -277,13 +286,13 @@ Translation APIs for Mediated Devices
>  =====================================
>  
>  The following APIs are provided for translating user pfn to host pfn in a VFIO
> -driver:
> +driver::
>  
> -extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
> -                          int npage, int prot, unsigned long *phys_pfn);
> +	extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
> +				  int npage, int prot, unsigned long *phys_pfn);
>  
> -extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
> -                            int npage);
> +	extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
> +				    int npage);
>  
>  These functions call back into the back-end IOMMU module by using the pin_pages
>  and unpin_pages callbacks of the struct vfio_iommu_driver_ops[4]. Currently
> @@ -304,81 +313,80 @@ card.
>  
>     This step creates a dummy device, /sys/devices/virtual/mtty/mtty/
>  
> -   Files in this device directory in sysfs are similar to the following:
> +   Files in this device directory in sysfs are similar to the following::
>  
> -   # tree /sys/devices/virtual/mtty/mtty/
> -      /sys/devices/virtual/mtty/mtty/
> -      |-- mdev_supported_types
> -      |   |-- mtty-1
> -      |   |   |-- available_instances
> -      |   |   |-- create
> -      |   |   |-- device_api
> -      |   |   |-- devices
> -      |   |   `-- name
> -      |   `-- mtty-2
> -      |       |-- available_instances
> -      |       |-- create
> -      |       |-- device_api
> -      |       |-- devices
> -      |       `-- name
> -      |-- mtty_dev
> -      |   `-- sample_mtty_dev
> -      |-- power
> -      |   |-- autosuspend_delay_ms
> -      |   |-- control
> -      |   |-- runtime_active_time
> -      |   |-- runtime_status
> -      |   `-- runtime_suspended_time
> -      |-- subsystem -> ../../../../class/mtty
> -      `-- uevent
> +     # tree /sys/devices/virtual/mtty/mtty/
> +        /sys/devices/virtual/mtty/mtty/
> +        |-- mdev_supported_types
> +        |   |-- mtty-1
> +        |   |   |-- available_instances
> +        |   |   |-- create
> +        |   |   |-- device_api
> +        |   |   |-- devices
> +        |   |   `-- name
> +        |   `-- mtty-2
> +        |       |-- available_instances
> +        |       |-- create
> +        |       |-- device_api
> +        |       |-- devices
> +        |       `-- name
> +        |-- mtty_dev
> +        |   `-- sample_mtty_dev
> +        |-- power
> +        |   |-- autosuspend_delay_ms
> +        |   |-- control
> +        |   |-- runtime_active_time
> +        |   |-- runtime_status
> +        |   `-- runtime_suspended_time
> +        |-- subsystem -> ../../../../class/mtty
> +        `-- uevent
>  
>  2. Create a mediated device by using the dummy device that you created in the
> -   previous step.
> +   previous step::
>  
> -   # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
> +     # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
>                /sys/devices/virtual/mtty/mtty/mdev_supported_types/mtty-2/create
>  
> -3. Add parameters to qemu-kvm.
> +3. Add parameters to qemu-kvm::
>  
> -   -device vfio-pci,\
> -    sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
> +     -device vfio-pci,\
> +      sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
>  
>  4. Boot the VM.
>  
>     In the Linux guest VM, with no hardware on the host, the device appears
> -   as  follows:
> +   as  follows::
>  
> -   # lspci -s 00:05.0 -xxvv
> -   00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
> -           Subsystem: Device 4348:3253
> -           Physical Slot: 5
> -           Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
> -   Stepping- SERR- FastB2B- DisINTx-
> -           Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
> -   <TAbort- <MAbort- >SERR- <PERR- INTx-
> -           Interrupt: pin A routed to IRQ 10
> -           Region 0: I/O ports at c150 [size=8]
> -           Region 1: I/O ports at c158 [size=8]
> -           Kernel driver in use: serial
> -   00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
> -   10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
> -   20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
> -   30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
> +     # lspci -s 00:05.0 -xxvv
> +     00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
> +             Subsystem: Device 4348:3253
> +             Physical Slot: 5
> +             Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
> +     Stepping- SERR- FastB2B- DisINTx-
> +             Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
> +     <TAbort- <MAbort- >SERR- <PERR- INTx-
> +             Interrupt: pin A routed to IRQ 10
> +             Region 0: I/O ports at c150 [size=8]
> +             Region 1: I/O ports at c158 [size=8]
> +             Kernel driver in use: serial
> +     00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
> +     10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
> +     20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
> +     30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
>  
> -   In the Linux guest VM, dmesg output for the device is as follows:
> +     In the Linux guest VM, dmesg output for the device is as follows:
>  
> -   serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ
> -10
> -   0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
> -   0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
> +     serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ 10
> +     0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
> +     0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
>  
>  
> -5. In the Linux guest VM, check the serial ports.
> +5. In the Linux guest VM, check the serial ports::
>  
> -   # setserial -g /dev/ttyS*
> -   /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
> -   /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
> -   /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
> +     # setserial -g /dev/ttyS*
> +     /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
> +     /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
> +     /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
>  
>  6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
>     /dev/ttyS2 with hardware flow control disabled.
> @@ -388,14 +396,14 @@ card.
>  
>     Data is loop backed from hosts mtty driver.
>  
> -8. Destroy the mediated device that you created.
> +8. Destroy the mediated device that you created::
>  
> -   # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
> +     # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
>  
>  References
>  ==========
>  
> -[1] See Documentation/vfio.txt 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
> +1. See Documentation/vfio.txt 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
> 

Re: [PATCH 01/29] pinctrl.txt: standardize document format

[Linus Walleij]

On Fri, May 19, 2017 at 3:25 AM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:

> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
>
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx.
>
> This document is almost following the standard stile.
>
> There are only two things to adjust on it:
>
> - promote the level of the document title;
> - mark literal blocks as such.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

I applied the patch fixing some of the indentation mistakes pointed
out by Geert.

Should the file be renamed pinctrl.rst now?

Yours,
Linus Walleij

Re: [PATCH 20/29] sync_file.txt: standardize document format

[Gustavo Padovan]

Hi Mauro,

2017-05-18 Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
> 
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> - Use markup for document title and authorship;
> - Mark literal blocks;
> - Use a numbered list for references.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/sync_file.txt | 23 +++++++++++++----------
>  1 file changed, 13 insertions(+), 10 deletions(-)

We went ahead and applied this to drm-misc-next. Thanks.

Gustavo

Re: [PATCH 20/29] sync_file.txt: standardize document format

[Mauro Carvalho Chehab]

Em Wed, 24 May 2017 22:36:36 -0300
Gustavo Padovan <gustavo@padovan.org> escreveu:

> Hi Mauro,
> 
> 2017-05-18 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> > 
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx:
> > - Use markup for document title and authorship;
> > - Mark literal blocks;
> > - Use a numbered list for references.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/sync_file.txt | 23 +++++++++++++----------
> >  1 file changed, 13 insertions(+), 10 deletions(-)  
> 
> We went ahead and applied this to drm-misc-next. Thanks.

OK!

Thanks!
Mauro

Re: [PATCH 12/29] rtc.txt: standardize document format

[Alexandre Belloni]

On 18/05/2017 at 22:25:56 -0300, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
> 
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> 
> - adjust identation of the titles;
> - mark a table as such;
> - don't capitalize chapter names.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/rtc.txt | 44 +++++++++++++++++++++++---------------------
>  1 file changed, 23 insertions(+), 21 deletions(-)
> 
Applied, thanks.

-- 
Alexandre Belloni, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com

[rtc-linux] Re: [PATCH 12/29] rtc.txt: standardize document format

[Alexandre Belloni]

On 18/05/2017 at 22:25:56 -0300, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
> 
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> 
> - adjust identation of the titles;
> - mark a table as such;
> - don't capitalize chapter names.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/rtc.txt | 44 +++++++++++++++++++++++---------------------
>  1 file changed, 23 insertions(+), 21 deletions(-)
> 
Applied, thanks.

-- 
Alexandre Belloni, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com

-- 
You received this message because you are subscribed to "rtc-linux".
Membership options at http://groups.google.com/group/rtc-linux .
Please read http://groups.google.com/group/rtc-linux/web/checklist
before submitting a driver.
--- 
You received this message because you are subscribed to the Google Groups "rtc-linux" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rtc-linux+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [PATCH 04/29] printk-formats.txt: standardize document format

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 16:37:34 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 05/19/17 13:28, Mauro Carvalho Chehab wrote:
> > Em Fri, 19 May 2017 03:26:08 -0700
> > Joe Perches <joe@perches.com> escreveu:
> >   
> >> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:  
> >>> Each text file under Documentation follows a different
> >>> format. Some doesn't even have titles!
> >>>
> >>> Change its representation to follow the adopted standard,
> >>> using ReST markups for it to be parseable by Sphinx:
> >>>
> >>> - add a title for the document;
> >>> - add markups for section titles;
> >>> - move authorship to the beginning and use :Author:;
> >>> - use right markup for tables;
> >>> - mark literals and literal blocks.    
> >>
> >> I think the .rst markup is far uglier to read as text
> >> and harder to modify for new additions to %p<foo>
> >> given column alignments.
> >>
> >> For instance below, but other than that, the .rst
> >> is easier to read.
> >>  
> >>> diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt    
> >> []  
> >>> @@ -1,139 +1,180 @@
> >>> -If variable is of Type,		use printk format specifier:
> >>> ----------------------------------------------------------
> >>> -		int			%d or %x
> >>> -		unsigned int		%u or %x
> >>> -		long			%ld or %lx
> >>> -		unsigned long		%lu or %lx
> >>> -		long long		%lld or %llx
> >>> -		unsigned long long	%llu or %llx
> >>> -		size_t			%zu or %zx
> >>> -		ssize_t			%zd or %zx
> >>> -		s32			%d or %x
> >>> -		u32			%u or %x
> >>> -		s64			%lld or %llx
> >>> -		u64			%llu or %llx    
> >> []  
> >>> +======================= ===========================
> >>> +If variable is of Type	use printk format specifier
> >>> +======================= ===========================
> >>> +``int``			``%d or %x``
> >>> +``unsigned int``	``%u or %x``
> >>> +``long``		``%ld or %lx``
> >>> +``unsigned long``	``%lu or %lx``
> >>> +``long long``		``%lld or %llx``
> >>> +``unsigned long long``	``%llu or %llx``
> >>> +``size_t``		``%zu or %zx``
> >>> +``ssize_t``		``%zd or %zx``
> >>> +``s32``			``%d or %x``
> >>> +``u32``			``%u or %x``
> >>> +``s64``			``%lld or %llx``
> >>> +``u64``			``%llu or %llx``
> >>> +======================= ===========================    
> > 
> > Well, we could,instead, use literal blocks, e. g. something like:
> > 
> > ::
> > 
> >  -If variable is of Type,		use printk format specifier:
> >  ----------------------------------------------------------
> >  -		int			%d or %x
> >  -		unsigned int		%u or %x
> >  -		long			%ld or %lx
> >  -		unsigned long		%lu or %lx
> >  -		long long		%lld or %llx
> >  -		unsigned long long	%llu or %llx
> >  -		size_t			%zu or %zx
> >  -		ssize_t			%zd or %zx
> >  -		s32			%d or %x
> >  -		u32			%u or %x
> >  -		s64			%lld or %llx
> >  -		u64			%llu or %llx  
> >   
> 
> I like that latter option.
> 
> thanks.

Sorry for taking so long to return to this thread... got sidetracked by two
trips.

Changed to avoid adding that many literal escaping sequences.
The end result, in HTML format is at:
	https://www.infradead.org/~mchehab/kernel_docs/unsorted/printk-formats.html

Patch enclosed.

Regards,
Mauro

-


[PATCH] printk-formats.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- add a title for the document;
- add markups for section titles;
- move authorship to the beginning and use :Author:;
- use right markup for tables;
- mark literals and literal blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..7824f8442ec4 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.txt
@@ -1,5 +1,18 @@
-If variable is of Type,		use printk format specifier:
----------------------------------------------------------
+=========================================
+How to get printk format specifiers right
+=========================================
+
+:Author: Randy Dunlap <rdunlap@infradead.org>
+:Author: Andrew Murray <amurray@mpc-data.co.uk>
+
+
+Integer types
+=============
+
+::
+
+	If variable is of Type,		use printk format specifier:
+	------------------------------------------------------------
 		int			%d or %x
 		unsigned int		%u or %x
 		long			%ld or %lx
@@ -13,25 +26,29 @@ If variable is of Type,		use printk format specifier:
 		s64			%lld or %llx
 		u64			%llu or %llx
 
-If <type> is dependent on a config option for its size (e.g., sector_t,
-blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
-format specifier of its largest possible type and explicitly cast to it.
-Example:
+If <type> is dependent on a config option for its size (e.g., ``sector_t``,
+``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
+use a format specifier of its largest possible type and explicitly cast to it.
+
+Example::
 
 	printk("test: sector number/total blocks: %llu/%llu\n",
 		(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: sizeof() result is of type size_t.
+Reminder: ``sizeof()`` result is of type ``size_t``.
 
-The kernel's printf does not support %n. For obvious reasons, floating
-point formats (%e, %f, %g, %a) are also not recognized. Use of any
+The kernel's printf does not support ``%n``. For obvious reasons, floating
+point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
 unsupported specifier or length qualifier results in a WARN and early
 return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
 
-Symbols/Function Pointers:
+Symbols/Function Pointers
+=========================
+
+::
 
 	%pF	versatile_init+0x0/0x110
 	%pf	versatile_init
@@ -41,99 +58,122 @@ Symbols/Function Pointers:
 	%ps	versatile_init
 	%pB	prev_fn_of_versatile_init+0x88/0x88
 
-	For printing symbols and function pointers. The 'S' and 's' specifiers
-	result in the symbol name with ('S') or without ('s') offsets. Where
-	this is used on a kernel without KALLSYMS - the symbol address is
-	printed instead.
+For printing symbols and function pointers. The ``S`` and ``s`` specifiers
+result in the symbol name with (``S``) or without (``s``) offsets. Where
+this is used on a kernel without KALLSYMS - the symbol address is
+printed instead.
+
+The ``B`` specifier results in the symbol name with offsets and should be
+used when printing stack backtraces. The specifier takes into
+consideration the effect of compiler optimisations which may occur
+when tail-call``s are used and marked with the noreturn GCC attribute.
 
-	The 'B' specifier results in the symbol name with offsets and should be
-	used when printing stack backtraces. The specifier takes into
-	consideration the effect of compiler optimisations which may occur
-	when tail-call's are used and marked with the noreturn GCC attribute.
+On ia64, ppc64 and parisc64 architectures function pointers are
+actually function descriptors which must first be resolved. The ``F`` and
+``f`` specifiers perform this resolution and then provide the same
+functionality as the ``S`` and ``s`` specifiers.
 
-	On ia64, ppc64 and parisc64 architectures function pointers are
-	actually function descriptors which must first be resolved. The 'F' and
-	'f' specifiers perform this resolution and then provide the same
-	functionality as the 'S' and 's' specifiers.
+Kernel Pointers
+===============
 
-Kernel Pointers:
+::
 
 	%pK	0x01234567 or 0x0123456789abcdef
 
-	For printing kernel pointers which should be hidden from unprivileged
-	users. The behaviour of %pK depends on the kptr_restrict sysctl - see
-	Documentation/sysctl/kernel.txt for more details.
+For printing kernel pointers which should be hidden from unprivileged
+users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see
+Documentation/sysctl/kernel.txt for more details.
 
-Struct Resources:
+Struct Resources
+================
+
+::
 
 	%pr	[mem 0x60000000-0x6fffffff flags 0x2200] or
 		[mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
 	%pR	[mem 0x60000000-0x6fffffff pref] or
 		[mem 0x0000000060000000-0x000000006fffffff pref]
 
-	For printing struct resources. The 'R' and 'r' specifiers result in a
-	printed resource with ('R') or without ('r') a decoded flags member.
-	Passed by reference.
+For printing struct resources. The ``R`` and ``r`` specifiers result in a
+printed resource with (``R``) or without (``r``) a decoded flags member.
+Passed by reference.
+
+Physical addresses types ``phys_addr_t``
+========================================
 
-Physical addresses types phys_addr_t:
+::
 
 	%pa[p]	0x01234567 or 0x0123456789abcdef
 
-	For printing a phys_addr_t type (and its derivatives, such as
-	resource_size_t) which can vary based on build options, regardless of
-	the width of the CPU data path. Passed by reference.
+For printing a ``phys_addr_t`` type (and its derivatives, such as
+``resource_size_t``) which can vary based on build options, regardless of
+the width of the CPU data path. Passed by reference.
 
-DMA addresses types dma_addr_t:
+DMA addresses types ``dma_addr_t``
+==================================
+
+::
 
 	%pad	0x01234567 or 0x0123456789abcdef
 
-	For printing a dma_addr_t type which can vary based on build options,
-	regardless of the width of the CPU data path. Passed by reference.
+For printing a ``dma_addr_t`` type which can vary based on build options,
+regardless of the width of the CPU data path. Passed by reference.
+
+Raw buffer as an escaped string
+===============================
 
-Raw buffer as an escaped string:
+::
 
 	%*pE[achnops]
 
-	For printing raw buffer as an escaped string. For the following buffer
+For printing raw buffer as an escaped string. For the following buffer::
 
 		1b 62 20 5c 43 07 22 90 0d 5d
 
-	few examples show how the conversion would be done (the result string
-	without surrounding quotes):
+few examples show how the conversion would be done (the result string
+without surrounding quotes)::
 
 		%*pE		"\eb \C\a"\220\r]"
 		%*pEhp		"\x1bb \C\x07"\x90\x0d]"
 		%*pEa		"\e\142\040\\\103\a\042\220\r\135"
 
-	The conversion rules are applied according to an optional combination
-	of flags (see string_escape_mem() kernel documentation for the
-	details):
-		a - ESCAPE_ANY
-		c - ESCAPE_SPECIAL
-		h - ESCAPE_HEX
-		n - ESCAPE_NULL
-		o - ESCAPE_OCTAL
-		p - ESCAPE_NP
-		s - ESCAPE_SPACE
-	By default ESCAPE_ANY_NP is used.
+The conversion rules are applied according to an optional combination
+of flags (see :c:func:`string_escape_mem` kernel documentation for the
+details):
+
+	- ``a`` - ESCAPE_ANY
+	- ``c`` - ESCAPE_SPECIAL
+	- ``h`` - ESCAPE_HEX
+	- ``n`` - ESCAPE_NULL
+	- ``o`` - ESCAPE_OCTAL
+	- ``p`` - ESCAPE_NP
+	- ``s`` - ESCAPE_SPACE
+
+By default ESCAPE_ANY_NP is used.
+
+ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
+printing SSIDs.
 
-	ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
-	printing SSIDs.
+If field width is omitted the 1 byte only will be escaped.
 
-	If field width is omitted the 1 byte only will be escaped.
+Raw buffer as a hex string
+==========================
 
-Raw buffer as a hex string:
+::
 
 	%*ph	00 01 02  ...  3f
 	%*phC	00:01:02: ... :3f
 	%*phD	00-01-02- ... -3f
 	%*phN	000102 ... 3f
 
-	For printing a small buffers (up to 64 bytes long) as a hex string with
-	certain separator. For the larger buffers consider to use
-	print_hex_dump().
+For printing a small buffers (up to 64 bytes long) as a hex string with
+certain separator. For the larger buffers consider to use
+:c:func:`print_hex_dump`.
 
-MAC/FDDI addresses:
+MAC/FDDI addresses
+==================
+
+::
 
 	%pM	00:01:02:03:04:05
 	%pMR	05:04:03:02:01:00
@@ -141,53 +181,62 @@ MAC/FDDI addresses:
 	%pm	000102030405
 	%pmR	050403020100
 
-	For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm'
-	specifiers result in a printed address with ('M') or without ('m') byte
-	separators. The default byte separator is the colon (':').
+For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
+specifiers result in a printed address with (``M``) or without (``m``) byte
+separators. The default byte separator is the colon (``:``).
+
+Where FDDI addresses are concerned the ``F`` specifier can be used after
+the ``M`` specifier to use dash (``-``) separators instead of the default
+separator.
 
-	Where FDDI addresses are concerned the 'F' specifier can be used after
-	the 'M' specifier to use dash ('-') separators instead of the default
-	separator.
+For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
+specifier to use reversed byte order suitable for visual interpretation
+of Bluetooth addresses which are in the little endian order.
 
-	For Bluetooth addresses the 'R' specifier shall be used after the 'M'
-	specifier to use reversed byte order suitable for visual interpretation
-	of Bluetooth addresses which are in the little endian order.
+Passed by reference.
 
-	Passed by reference.
+IPv4 addresses
+==============
 
-IPv4 addresses:
+::
 
 	%pI4	1.2.3.4
 	%pi4	001.002.003.004
 	%p[Ii]4[hnbl]
 
-	For printing IPv4 dot-separated decimal addresses. The 'I4' and 'i4'
-	specifiers result in a printed address with ('i4') or without ('I4')
-	leading zeros.
+For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
+specifiers result in a printed address with (``i4``) or without (``I4``)
+leading zeros.
 
-	The additional 'h', 'n', 'b', and 'l' specifiers are used to specify
-	host, network, big or little endian order addresses respectively. Where
-	no specifier is provided the default network/big endian order is used.
+The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
+host, network, big or little endian order addresses respectively. Where
+no specifier is provided the default network/big endian order is used.
 
-	Passed by reference.
+Passed by reference.
 
-IPv6 addresses:
+IPv6 addresses
+==============
+
+::
 
 	%pI6	0001:0002:0003:0004:0005:0006:0007:0008
 	%pi6	00010002000300040005000600070008
 	%pI6c	1:2:3:4:5:6:7:8
 
-	For printing IPv6 network-order 16-bit hex addresses. The 'I6' and 'i6'
-	specifiers result in a printed address with ('I6') or without ('i6')
-	colon-separators. Leading zeros are always used.
+For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
+specifiers result in a printed address with (``I6``) or without (``i6``)
+colon-separators. Leading zeros are always used.
+
+The additional ``c`` specifier can be used with the ``I`` specifier to
+print a compressed IPv6 address as described by
+http://tools.ietf.org/html/rfc5952
 
-	The additional 'c' specifier can be used with the 'I' specifier to
-	print a compressed IPv6 address as described by
-	http://tools.ietf.org/html/rfc5952
+Passed by reference.
 
-	Passed by reference.
+IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
+=========================================================
 
-IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
+::
 
 	%pIS	1.2.3.4		or 0001:0002:0003:0004:0005:0006:0007:0008
 	%piS	001.002.003.004	or 00010002000300040005000600070008
@@ -195,141 +244,161 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
 	%pISpc	1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345
 	%p[Ii]S[pfschnbl]
 
-	For printing an IP address without the need to distinguish whether it's
-	of type AF_INET or AF_INET6, a pointer to a valid 'struct sockaddr',
-	specified through 'IS' or 'iS', can be passed to this format specifier.
+For printing an IP address without the need to distinguish whether it``s
+of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``,
+specified through ``IS`` or ``iS``, can be passed to this format specifier.
 
-	The additional 'p', 'f', and 's' specifiers are used to specify port
-	(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ':' prefix,
-	flowinfo a '/' and scope a '%', each followed by the actual value.
+The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
+(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
+flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
 
-	In case of an IPv6 address the compressed IPv6 address as described by
-	http://tools.ietf.org/html/rfc5952 is being used if the additional
-	specifier 'c' is given. The IPv6 address is surrounded by '[', ']' in
-	case of additional specifiers 'p', 'f' or 's' as suggested by
-	https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
+In case of an IPv6 address the compressed IPv6 address as described by
+http://tools.ietf.org/html/rfc5952 is being used if the additional
+specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
+case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
+https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
 
-	In case of IPv4 addresses, the additional 'h', 'n', 'b', and 'l'
-	specifiers can be used as well and are ignored in case of an IPv6
-	address.
+In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
+specifiers can be used as well and are ignored in case of an IPv6
+address.
 
-	Passed by reference.
+Passed by reference.
 
-	Further examples:
+Further examples::
 
 	%pISfc		1.2.3.4		or [1:2:3:4:5:6:7:8]/123456789
 	%pISsc		1.2.3.4		or [1:2:3:4:5:6:7:8]%1234567890
 	%pISpfc		1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345/123456789
 
-UUID/GUID addresses:
+UUID/GUID addresses
+===================
+
+::
 
 	%pUb	00010203-0405-0607-0809-0a0b0c0d0e0f
 	%pUB	00010203-0405-0607-0809-0A0B0C0D0E0F
 	%pUl	03020100-0504-0706-0809-0a0b0c0e0e0f
 	%pUL	03020100-0504-0706-0809-0A0B0C0E0E0F
 
-	For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
-	'b' and 'B' specifiers are used to specify a little endian order in
-	lower ('l') or upper case ('L') hex characters - and big endian order
-	in lower ('b') or upper case ('B') hex characters.
+For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
+'b' and 'B' specifiers are used to specify a little endian order in
+lower ('l') or upper case ('L') hex characters - and big endian order
+in lower ('b') or upper case ('B') hex characters.
+
+Where no additional specifiers are used the default big endian
+order with lower case hex characters will be printed.
 
-	Where no additional specifiers are used the default big endian
-	order with lower case hex characters will be printed.
+Passed by reference.
 
-	Passed by reference.
+dentry names
+============
 
-dentry names:
+::
 
 	%pd{,2,3,4}
 	%pD{,2,3,4}
 
-	For printing dentry name; if we race with d_move(), the name might be
-	a mix of old and new ones, but it won't oops.  %pd dentry is a safer
-	equivalent of %s dentry->d_name.name we used to use, %pd<n> prints
-	n last components.  %pD does the same thing for struct file.
+For printing dentry name; if we race with :c:func:`d_move`, the name might be
+a mix of old and new ones, but it won't oops.  ``%pd`` dentry is a safer
+equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints
+``n`` last components.  ``%pD`` does the same thing for struct file.
+
+Passed by reference.
 
-	Passed by reference.
+block_device names
+==================
 
-block_device names:
+::
 
 	%pg	sda, sda1 or loop0p1
 
-	For printing name of block_device pointers.
+For printing name of block_device pointers.
 
-struct va_format:
+struct va_format
+================
+
+::
 
 	%pV
 
-	For printing struct va_format structures. These contain a format string
-	and va_list as follows:
+For printing struct va_format structures. These contain a format string
+and va_list as follows::
 
 	struct va_format {
 		const char *fmt;
 		va_list *va;
 	};
 
-	Implements a "recursive vsnprintf".
+Implements a "recursive vsnprintf".
+
+Do not use this feature without some mechanism to verify the
+correctness of the format string and va_list arguments.
 
-	Do not use this feature without some mechanism to verify the
-	correctness of the format string and va_list arguments.
+Passed by reference.
 
-	Passed by reference.
+struct clk
+==========
 
-struct clk:
+::
 
 	%pC	pll1
 	%pCn	pll1
 	%pCr	1560000000
 
-	For printing struct clk structures. '%pC' and '%pCn' print the name
-	(Common Clock Framework) or address (legacy clock framework) of the
-	structure; '%pCr' prints the current clock rate.
+For printing struct clk structures. ``%pC`` and ``%pCn`` print the name
+(Common Clock Framework) or address (legacy clock framework) of the
+structure; ``%pCr`` prints the current clock rate.
 
-	Passed by reference.
+Passed by reference.
 
-bitmap and its derivatives such as cpumask and nodemask:
+bitmap and its derivatives such as cpumask and nodemask
+=======================================================
+
+::
 
 	%*pb	0779
 	%*pbl	0,3-6,8-10
 
-	For printing bitmap and its derivatives such as cpumask and nodemask,
-	%*pb output the bitmap with field width as the number of bits and %*pbl
-	output the bitmap as range list with field width as the number of bits.
+For printing bitmap and its derivatives such as cpumask and nodemask,
+``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl``
+output the bitmap as range list with field width as the number of bits.
+
+Passed by reference.
 
-	Passed by reference.
+Flags bitfields such as page flags, gfp_flags
+=============================================
 
-Flags bitfields such as page flags, gfp_flags:
+::
 
 	%pGp	referenced|uptodate|lru|active|private
 	%pGg	GFP_USER|GFP_DMA32|GFP_NOWARN
 	%pGv	read|exec|mayread|maywrite|mayexec|denywrite
 
-	For printing flags bitfields as a collection of symbolic constants that
-	would construct the value. The type of flags is given by the third
-	character. Currently supported are [p]age flags, [v]ma_flags (both
-	expect unsigned long *) and [g]fp_flags (expects gfp_t *). The flag
-	names and print order depends on the particular	type.
+For printing flags bitfields as a collection of symbolic constants that
+would construct the value. The type of flags is given by the third
+character. Currently supported are [p]age flags, [v]ma_flags (both
+expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
+names and print order depends on the particular	type.
 
-	Note that this format should not be used directly in TP_printk() part
-	of a tracepoint. Instead, use the show_*_flags() functions from
-	<trace/events/mmflags.h>.
+Note that this format should not be used directly in :c:func:`TP_printk()` part
+of a tracepoint. Instead, use the ``show_*_flags()`` functions from
+<trace/events/mmflags.h>.
 
-	Passed by reference.
+Passed by reference.
 
-Network device features:
+Network device features
+=======================
+
+::
 
 	%pNF	0x000000000000c000
 
-	For printing netdev_features_t.
+For printing netdev_features_t.
 
-	Passed by reference.
+Passed by reference.
 
-If you add other %p extensions, please extend lib/test_printf.c with
+If you add other ``%p`` extensions, please extend lib/test_printf.c with
 one or more test cases, if at all feasible.
 
 
 Thank you for your cooperation and attention.
-
-
-By Randy Dunlap <rdunlap@infradead.org> and
-Andrew Murray <amurray@mpc-data.co.uk>

Re: [PATCH 01/29] pinctrl.txt: standardize document format

[Mauro Carvalho Chehab]

Em Tue, 23 May 2017 11:12:43 +0200
Linus Walleij <linus.walleij@linaro.org> escreveu:

> On Fri, May 19, 2017 at 3:25 AM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> 
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> >
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx.
> >
> > This document is almost following the standard stile.
> >
> > There are only two things to adjust on it:
> >
> > - promote the level of the document title;
> > - mark literal blocks as such.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>  
> 
> I applied the patch fixing some of the indentation mistakes pointed
> out by Geert.

Thanks!

(sorry for not answering earlier... got sidetracked by two trips)

> Should the file be renamed pinctrl.rst now?

If you just rename it, Sphinx will complain because it doesn't
belong to any index.rst file. As this is part of drivers/, I guess
the right thing is to add it to driver-api book.

The enclosed patch should be doing it (it is based on linux-next).

Thanks,
Mauro

[PATCH] pinctrl.txt: move it to the driver-api book

As pinctrl describes a feature from drivers/base, place it at
the right book.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 3cf1acebc4ee..7c94ab50afed 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -43,6 +43,7 @@ available subsections can be seen below.
    80211/index
    uio-howto
    firmware/index
+   pinctl
    misc_devices
 
 .. only::  subproject and html
diff --git a/Documentation/pinctrl.txt b/Documentation/driver-api/pinctl.rst
similarity index 100%
rename from Documentation/pinctrl.txt
rename to Documentation/driver-api/pinctl.rst

Re: [PATCH 01/29] pinctrl.txt: standardize document format

[Linus Walleij]

On Sat, Jun 17, 2017 at 5:03 PM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Linus Walleij <linus.walleij@linaro.org> escreveu:

>> Should the file be renamed pinctrl.rst now?
>
> If you just rename it, Sphinx will complain because it doesn't
> belong to any index.rst file. As this is part of drivers/, I guess
> the right thing is to add it to driver-api book.
>
> The enclosed patch should be doing it (it is based on linux-next).

Hey it just applies, so I tossed in this patch too, thanks a lot!

Yours,
Linus Walleij