Re: [PATCH 10/30] kobject.txt: standardize document format

[Greg Kroah-Hartman]

On Thu, May 18, 2017 at 10:24:02PM -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 markups for titles;
> - mark literal blocks as such;
> - add needed whitespace/blank lines;
> - use :Author: and :Last updated: for authorship.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Acked-by: Greg Kroah-Hartman 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 04/10] MAINTAINERS: update file entries for Coresight subsystem

[Leo Yan]

Update document file entries for Coresight debug module.

Reviewed-by: Mathieu Poirier 
Signed-off-by: Leo Yan 
---
 MAINTAINERS | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index f7d568b..d443258 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1208,7 +1208,9 @@ L:linux-arm-ker...@lists.infradead.org (moderated 
for non-subscribers)
 S: Maintained
 F: drivers/hwtracing/coresight/*
 F: Documentation/trace/coresight.txt
+F: Documentation/trace/coresight-cpu-debug.txt
 F: Documentation/devicetree/bindings/arm/coresight.txt
+F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
 F: Documentation/ABI/testing/sysfs-bus-coresight-devices-*
 F: tools/perf/arch/arm/util/pmu.c
 F: tools/perf/arch/arm/util/auxtrace.c
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 06/10] coresight: refactor with function of_coresight_get_cpu

[Leo Yan]

This is refactor to add function of_coresight_get_cpu(), so it's used to
retrieve CPU id for coresight component. Finally can use it as a common
function for multiple places.

Suggested-by: Mathieu Poirier 
Reviewed-by: Suzuki K Poulose 
Signed-off-by: Leo Yan 
---
 drivers/hwtracing/coresight/of_coresight.c | 43 +++---
 include/linux/coresight.h  |  3 +++
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/drivers/hwtracing/coresight/of_coresight.c 
b/drivers/hwtracing/coresight/of_coresight.c
index 225b2dd..a187941 100644
--- a/drivers/hwtracing/coresight/of_coresight.c
+++ b/drivers/hwtracing/coresight/of_coresight.c
@@ -101,16 +101,40 @@ static int of_coresight_alloc_memory(struct device *dev,
return 0;
 }
 
+int of_coresight_get_cpu(const struct device_node *node)
+{
+   int cpu;
+   bool found;
+   struct device_node *dn, *np;
+
+   dn = of_parse_phandle(node, "cpu", 0);
+
+   /* Affinity defaults to CPU0 */
+   if (!dn)
+   return 0;
+
+   for_each_possible_cpu(cpu) {
+   np = of_cpu_device_node_get(cpu);
+   found = (dn == np);
+   of_node_put(np);
+   if (found)
+   break;
+   }
+   of_node_put(dn);
+
+   /* Affinity to CPU0 if no cpu nodes are found */
+   return found ? cpu : 0;
+}
+EXPORT_SYMBOL_GPL(of_coresight_get_cpu);
+
 struct coresight_platform_data *
 of_get_coresight_platform_data(struct device *dev,
   const struct device_node *node)
 {
-   int i = 0, ret = 0, cpu;
+   int i = 0, ret = 0;
struct coresight_platform_data *pdata;
struct of_endpoint endpoint, rendpoint;
struct device *rdev;
-   bool found;
-   struct device_node *dn, *np;
struct device_node *ep = NULL;
struct device_node *rparent = NULL;
struct device_node *rport = NULL;
@@ -177,18 +201,7 @@ of_get_coresight_platform_data(struct device *dev,
} while (ep);
}
 
-   dn = of_parse_phandle(node, "cpu", 0);
-   for_each_possible_cpu(cpu) {
-   np = of_cpu_device_node_get(cpu);
-   found = (dn == np);
-   of_node_put(np);
-   if (found)
-   break;
-   }
-   of_node_put(dn);
-
-   /* Affinity to CPU0 if no cpu nodes are found */
-   pdata->cpu = found ? cpu : 0;
+   pdata->cpu = of_coresight_get_cpu(node);
 
return pdata;
 }
diff --git a/include/linux/coresight.h b/include/linux/coresight.h
index bf0aa50..d950dad 100644
--- a/include/linux/coresight.h
+++ b/include/linux/coresight.h
@@ -263,10 +263,13 @@ static inline int coresight_timeout(void __iomem *addr, 
u32 offset,
 #endif
 
 #ifdef CONFIG_OF
+extern int of_coresight_get_cpu(const struct device_node *node);
 extern struct coresight_platform_data *
 of_get_coresight_platform_data(struct device *dev,
   const struct device_node *node);
 #else
+static inline int of_coresight_get_cpu(const struct device_node *node)
+{ return 0; }
 static inline struct coresight_platform_data *of_get_coresight_platform_data(
struct device *dev, const struct device_node *node) { return NULL; }
 #endif
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 10/10] arm64: dts: juno: Add Coresight CPU debug nodes

[Leo Yan]

From: Suzuki K Poulose 

Add Coresight CPU debug nodes for Juno r0, r1 & r2. The CPU
debug areas are mapped at the same address for all revisions,
like the ETM, even though the CPUs have changed from r1 to r2.

Cc: Sudeep Holla 
Cc: Leo Yan 
Cc: Mathieu Poirier 
Cc: Liviu Dudau 
Signed-off-by: Suzuki K Poulose 
---
 arch/arm64/boot/dts/arm/juno-base.dtsi | 54 ++
 arch/arm64/boot/dts/arm/juno-r1.dts| 24 +++
 arch/arm64/boot/dts/arm/juno-r2.dts| 24 +++
 arch/arm64/boot/dts/arm/juno.dts   | 24 +++
 4 files changed, 126 insertions(+)

diff --git a/arch/arm64/boot/dts/arm/juno-base.dtsi 
b/arch/arm64/boot/dts/arm/juno-base.dtsi
index bfe7d68..784a80a 100644
--- a/arch/arm64/boot/dts/arm/juno-base.dtsi
+++ b/arch/arm64/boot/dts/arm/juno-base.dtsi
@@ -216,6 +216,15 @@
};
};
 
+   cpu_debug0: cpu_debug@2201 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2201 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
funnel@220c { /* cluster0 funnel */
compatible = "arm,coresight-funnel", "arm,primecell";
reg = <0 0x220c 0 0x1000>;
@@ -266,6 +275,15 @@
};
};
 
+   cpu_debug1: cpu_debug@2211 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2211 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
etm2: etm@2304 {
compatible = "arm,coresight-etm4x", "arm,primecell";
reg = <0 0x2304 0 0x1000>;
@@ -280,6 +298,15 @@
};
};
 
+   cpu_debug2: cpu_debug@2301 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2301 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
funnel@230c { /* cluster1 funnel */
compatible = "arm,coresight-funnel", "arm,primecell";
reg = <0 0x230c 0 0x1000>;
@@ -344,6 +371,15 @@
};
};
 
+   cpu_debug3: cpu_debug@2311 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2311 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
etm4: etm@2324 {
compatible = "arm,coresight-etm4x", "arm,primecell";
reg = <0 0x2324 0 0x1000>;
@@ -358,6 +394,15 @@
};
};
 
+   cpu_debug4: cpu_debug@2321 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2321 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
etm5: etm@2334 {
compatible = "arm,coresight-etm4x", "arm,primecell";
reg = <0 0x2334 0 0x1000>;
@@ -372,6 +417,15 @@
};
};
 
+   cpu_debug5: cpu_debug@2331 {
+   compatible = "arm,coresight-cpu-debug", "arm,primecell";
+   reg = <0 0x2331 0 0x1000>;
+
+   clocks = <_smc50mhz>;
+   clock-names = "apb_pclk";
+   power-domains = <_devpd 0>;
+   };
+
replicator@2012 {
compatible = "qcom,coresight-replicator1x", "arm,primecell";
reg = <0 0x2012 0 0x1000>;
diff --git a/arch/arm64/boot/dts/arm/juno-r1.dts 
b/arch/arm64/boot/dts/arm/juno-r1.dts
index 0e8943a..aed6389 100644
--- a/arch/arm64/boot/dts/arm/juno-r1.dts
+++ b/arch/arm64/boot/dts/arm/juno-r1.dts
@@ -281,3 +281,27 @@
 _out_port {
remote-endpoint = <_funnel_in_port0>;
 };
+
+_debug0 {
+   cpu = <_0>;
+};
+
+_debug1 {
+   cpu = <_1>;
+};
+
+_debug2 {
+   cpu = <_0>;
+};
+
+_debug3 {
+   cpu = <_1>;
+};
+
+_debug4 {
+   cpu = <_2>;
+};
+
+_debug5 {
+   cpu = <_3>;
+};
diff --git a/arch/arm64/boot/dts/arm/juno-r2.dts 
b/arch/arm64/boot/dts/arm/juno-r2.dts
index 405e2fb..b39b6d6 100644
--- a/arch/arm64/boot/dts/arm/juno-r2.dts
+++ b/arch/arm64/boot/dts/arm/juno-r2.dts
@@ -281,3 +281,27 @@
 _out_port {
remote-endpoint = <_funnel_in_port0>;
 };
+
+_debug0 {
+   cpu = <_0>;
+};
+
+_debug1 {
+   cpu = <_1>;
+};
+
+_debug2 {
+   cpu = <_0>;
+};
+
+_debug3 {
+   cpu = <_1>;
+};
+
+_debug4 {
+   cpu = <_2>;
+};
+
+_debug5 {

[PATCH v10 09/10] arm64: dts: qcom: msm8916: Add debug unit

[Leo Yan]

Add debug unit on Qualcomm msm8916 based platforms, including the
DragonBoard 410c board.

Reviewed-by: Mathieu Poirier 
Signed-off-by: Leo Yan 
---
 arch/arm64/boot/dts/qcom/msm8916.dtsi | 32 
 1 file changed, 32 insertions(+)

diff --git a/arch/arm64/boot/dts/qcom/msm8916.dtsi 
b/arch/arm64/boot/dts/qcom/msm8916.dtsi
index ab30939..17691ab 100644
--- a/arch/arm64/boot/dts/qcom/msm8916.dtsi
+++ b/arch/arm64/boot/dts/qcom/msm8916.dtsi
@@ -1116,6 +1116,38 @@
};
};
 
+   debug@85 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0x85 0x1000>;
+   clocks = < RPM_QDSS_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@852000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0x852000 0x1000>;
+   clocks = < RPM_QDSS_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@854000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0x854000 0x1000>;
+   clocks = < RPM_QDSS_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@856000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0x856000 0x1000>;
+   clocks = < RPM_QDSS_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
etm@85c000 {
compatible = "arm,coresight-etm4x", "arm,primecell";
reg = <0x85c000 0x1000>;
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 08/10] arm64: dts: hi6220: register debug module

[Leo Yan]

Bind debug module driver for Hi6220.

Reviewed-by: Mathieu Poirier 
Signed-off-by: Leo Yan 
---
 arch/arm64/boot/dts/hisilicon/hi6220.dtsi | 64 +++
 1 file changed, 64 insertions(+)

diff --git a/arch/arm64/boot/dts/hisilicon/hi6220.dtsi 
b/arch/arm64/boot/dts/hisilicon/hi6220.dtsi
index 1e5129b..21805b9 100644
--- a/arch/arm64/boot/dts/hisilicon/hi6220.dtsi
+++ b/arch/arm64/boot/dts/hisilicon/hi6220.dtsi
@@ -916,5 +916,69 @@
};
};
};
+
+   debug@f659 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf659 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f6592000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf6592000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f6594000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf6594000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f6596000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf6596000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f65d {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf65d 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f65d2000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf65d2000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f65d4000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf65d4000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
+
+   debug@f65d6000 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf65d6000 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
};
 };
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 07/10] coresight: add support for CPU debug module

[Leo Yan]

Coresight includes debug module and usually the module connects with CPU
debug logic. ARMv8 architecture reference manual (ARM DDI 0487A.k) has
description for related info in "Part H: External Debug".

Chapter H7 "The Sample-based Profiling Extension" introduces several
sampling registers, e.g. we can check program counter value with
combined CPU exception level, secure state, etc. So this is helpful for
analysis CPU lockup scenarios, e.g. if one CPU has run into infinite
loop with IRQ disabled. In this case the CPU cannot switch context and
handle any interrupt (including IPIs), as the result it cannot handle
SMP call for stack dump.

This patch is to enable coresight debug module, so firstly this driver
is to bind apb clock for debug module and this is to ensure the debug
module can be accessed from program or external debugger. And the driver
uses sample-based registers for debug purpose, e.g. when system triggers
panic, the driver will dump program counter and combined context
registers (EDCIDSR, EDVIDSR); by parsing context registers so can
quickly get to know CPU secure state, exception level, etc.

Some of the debug module registers are located in CPU power domain, so
this requires the CPU power domain stays on when access related debug
registers, but the power management for CPU power domain is quite
dependent on SoC integration for power management. For the platforms
which with sane power controller implementations, this driver follows
the method to set EDPRCR to try to pull the CPU out of low power state
and then set 'no power down request' bit so the CPU has no chance to
lose power.

If the SoC has not followed up this design well for power management
controller, the user should use the command line parameter or sysfs
to constrain all or partial idle states to ensure the CPU power
domain is enabled and access coresight CPU debug component safely.

Reviewed-by: Suzuki K Poulose 
Signed-off-by: Leo Yan 
---
 drivers/hwtracing/coresight/Kconfig   |  14 +
 drivers/hwtracing/coresight/Makefile  |   1 +
 drivers/hwtracing/coresight/coresight-cpu-debug.c | 696 ++
 3 files changed, 711 insertions(+)
 create mode 100644 drivers/hwtracing/coresight/coresight-cpu-debug.c

diff --git a/drivers/hwtracing/coresight/Kconfig 
b/drivers/hwtracing/coresight/Kconfig
index 130cb21..8d55d6d 100644
--- a/drivers/hwtracing/coresight/Kconfig
+++ b/drivers/hwtracing/coresight/Kconfig
@@ -89,4 +89,18 @@ config CORESIGHT_STM
  logging useful software events or data coming from various entities
  in the system, possibly running different OSs
 
+config CORESIGHT_CPU_DEBUG
+   tristate "CoreSight CPU Debug driver"
+   depends on ARM || ARM64
+   depends on DEBUG_FS
+   help
+ This driver provides support for coresight debugging module. This
+ is primarily used to dump sample-based profiling registers when
+ system triggers panic, the driver will parse context registers so
+ can quickly get to know program counter (PC), secure state,
+ exception level, etc. Before use debugging functionality, platform
+ needs to ensure the clock domain and power domain are enabled
+ properly, please refer Documentation/trace/coresight-cpu-debug.txt
+ for detailed description and the example for usage.
+
 endif
diff --git a/drivers/hwtracing/coresight/Makefile 
b/drivers/hwtracing/coresight/Makefile
index af480d9..433d590 100644
--- a/drivers/hwtracing/coresight/Makefile
+++ b/drivers/hwtracing/coresight/Makefile
@@ -16,3 +16,4 @@ obj-$(CONFIG_CORESIGHT_SOURCE_ETM4X) += coresight-etm4x.o \
coresight-etm4x-sysfs.o
 obj-$(CONFIG_CORESIGHT_QCOM_REPLICATOR) += coresight-replicator-qcom.o
 obj-$(CONFIG_CORESIGHT_STM) += coresight-stm.o
+obj-$(CONFIG_CORESIGHT_CPU_DEBUG) += coresight-cpu-debug.o
diff --git a/drivers/hwtracing/coresight/coresight-cpu-debug.c 
b/drivers/hwtracing/coresight/coresight-cpu-debug.c
new file mode 100644
index 000..3589174
--- /dev/null
+++ b/drivers/hwtracing/coresight/coresight-cpu-debug.c
@@ -0,0 +1,696 @@
+/*
+ * Copyright (c) 2017 Linaro Limited. All rights reserved.
+ *
+ * Author: Leo Yan 
+ *
+ * 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.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see .
+ *
+ */
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 

[PATCH v10 05/10] coresight: of_get_coresight_platform_data: Add missing of_node_put

[Leo Yan]

From: Suzuki K Poulose 

The of_get_coresight_platform_data iterates over the possible CPU nodes
to find a given cpu phandle. However it does not drop the reference
to the node pointer returned by the of_get_coresight_platform_data.

This patch also introduces another minor fix is to use
of_cpu_device_node_get() to replace of_get_cpu_node().

Cc: Mathieu Poirier 
Reviewed-by: Suzuki K Poulose 
Signed-off-by: Suzuki K Poulose 
[Leo: minor tweaks for of_get_coresight_platform_data]
Signed-off-by: Leo Yan 
---
 drivers/hwtracing/coresight/of_coresight.c | 17 ++---
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/drivers/hwtracing/coresight/of_coresight.c 
b/drivers/hwtracing/coresight/of_coresight.c
index 2749853..225b2dd 100644
--- a/drivers/hwtracing/coresight/of_coresight.c
+++ b/drivers/hwtracing/coresight/of_coresight.c
@@ -109,7 +109,8 @@ of_get_coresight_platform_data(struct device *dev,
struct coresight_platform_data *pdata;
struct of_endpoint endpoint, rendpoint;
struct device *rdev;
-   struct device_node *dn;
+   bool found;
+   struct device_node *dn, *np;
struct device_node *ep = NULL;
struct device_node *rparent = NULL;
struct device_node *rport = NULL;
@@ -176,17 +177,19 @@ of_get_coresight_platform_data(struct device *dev,
} while (ep);
}
 
-   /* Affinity defaults to CPU0 */
-   pdata->cpu = 0;
dn = of_parse_phandle(node, "cpu", 0);
-   for (cpu = 0; dn && cpu < nr_cpu_ids; cpu++) {
-   if (dn == of_get_cpu_node(cpu, NULL)) {
-   pdata->cpu = cpu;
+   for_each_possible_cpu(cpu) {
+   np = of_cpu_device_node_get(cpu);
+   found = (dn == np);
+   of_node_put(np);
+   if (found)
break;
-   }
}
of_node_put(dn);
 
+   /* Affinity to CPU0 if no cpu nodes are found */
+   pdata->cpu = found ? cpu : 0;
+
return pdata;
 }
 EXPORT_SYMBOL_GPL(of_get_coresight_platform_data);
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 03/10] doc: Add coresight_cpu_debug.enable to kernel-parameters.txt

[Leo Yan]

Add coresight_cpu_debug.enable to kernel-parameters.txt, this flag is
used to enable/disable the CPU sampling based debugging.

Reviewed-by: Mathieu Poirier 
Signed-off-by: Leo Yan 
---
 Documentation/admin-guide/kernel-parameters.txt | 7 +++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/admin-guide/kernel-parameters.txt 
b/Documentation/admin-guide/kernel-parameters.txt
index 15f79c2..ff67ad7 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -649,6 +649,13 @@
/proc//coredump_filter.
See also Documentation/filesystems/proc.txt.
 
+   coresight_cpu_debug.enable
+   [ARM,ARM64]
+   Format: 
+   Enable/disable the CPU sampling based debugging.
+   0: default value, disable debugging
+   1: enable debugging at boot time
+
cpuidle.off=1   [CPU_IDLE]
disable the cpuidle sub-system
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 01/10] coresight: bindings for CPU debug module

[Leo Yan]

According to ARMv8 architecture reference manual (ARM DDI 0487A.k)
Chapter 'Part H: External debug', the CPU can integrate debug module
and it can support self-hosted debug and external debug. Especially
for supporting self-hosted debug, this means the program can access
the debug module from mmio region; and usually the mmio region is
integrated with coresight.

So add document for binding debug component, includes binding to APB
clock; and also need specify the CPU node which the debug module is
dedicated to specific CPU.

Suggested-by: Mike Leach 
Reviewed-by: Mathieu Poirier 
Reviewed-by: Suzuki K Poulose 
Acked-by: Rob Herring 
Signed-off-by: Leo Yan 
---
 .../bindings/arm/coresight-cpu-debug.txt   | 49 ++
 1 file changed, 49 insertions(+)
 create mode 100644 
Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt

diff --git a/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt 
b/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
new file mode 100644
index 000..2982912
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
@@ -0,0 +1,49 @@
+* CoreSight CPU Debug Component:
+
+CoreSight CPU debug component are compliant with the ARMv8 architecture
+reference manual (ARM DDI 0487A.k) Chapter 'Part H: External debug'. The
+external debug module is mainly used for two modes: self-hosted debug and
+external debug, and it can be accessed from mmio region from Coresight
+and eventually the debug module connects with CPU for debugging. And the
+debug module provides sample-based profiling extension, which can be used
+to sample CPU program counter, secure state and exception level, etc;
+usually every CPU has one dedicated debug module to be connected.
+
+Required properties:
+
+- compatible : should be "arm,coresight-cpu-debug"; supplemented with
+   "arm,primecell" since this driver is using the AMBA bus
+  interface.
+
+- reg : physical base address and length of the register set.
+
+- clocks : the clock associated to this component.
+
+- clock-names : the name of the clock referenced by the code. Since we are
+using the AMBA framework, the name of the clock providing
+   the interconnect should be "apb_pclk" and the clock is
+   mandatory. The interface between the debug logic and the
+   processor core is clocked by the internal CPU clock, so it
+   is enabled with CPU clock by default.
+
+- cpu : the CPU phandle the debug module is affined to. When omitted
+   the module is considered to belong to CPU0.
+
+Optional properties:
+
+- power-domains: a phandle to the debug power domain. We use "power-domains"
+ binding to turn on the debug logic if it has own dedicated
+power domain and if necessary to use "cpuidle.off=1" or
+"nohlt" in the kernel command line or sysfs node to
+constrain idle states to ensure registers in the CPU power
+domain are accessible.
+
+Example:
+
+   debug@f659 {
+   compatible = "arm,coresight-cpu-debug","arm,primecell";
+   reg = <0 0xf659 0 0x1000>;
+   clocks = <_ctrl HI6220_DAPB_CLK>;
+   clock-names = "apb_pclk";
+   cpu = <>;
+   };
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v10 00/10] coresight: enable debug module

[Leo Yan]

ARMv8 architecture reference manual (ARM DDI 0487A.k) Chapter H7 "The
Sample-based Profiling Extension" has description for sampling
registers, we can utilize these registers to check program counter
value with combined CPU exception level, secure state, etc. So this is
helpful for CPU lockup bugs, e.g. if one CPU has run into infinite loop
with IRQ disabled; the 'hang' CPU cannot switch context and handle any
interrupt, so it cannot handle SMP call for stack dump, etc.

This patch series is to enable coresight debug module with sample-based
registers and register call back notifier for PCSR register dumping
when panic happens, so we can see below dumping info for panic; and
this patch series has considered the conditions for access permission
for debug registers self, so this can avoid access debug registers when
CPU power domain is off; the driver also try to figure out the CPU is
in secure or non-secure state.

Patch 0001 is to document the dt binding; patch 0002 adds one detailed
document to describe the Coresight debug module implementation, the
clock and power domain impaction on the driver, some examples for usage.

Patch 0003 is to document boot parameters used in kernel command line.

Patch 0004 is to add file entries for MAINTAINERS.

Patch 0005 is used to fix the func of_get_coresight_platform_data()
doesn't properly drop the reference to the CPU node pointer; and
patch 0006 is refactor to add new function of_coresight_get_cpu().

Patch 0007 is the driver for CPU debug module.

Patch 0008 in this series are to enable debug unit on 96boards Hikey,
Patch 0009 is to enable debug on 96boards DB410c. Have verified on both
two boards.
Patch 0010 is to add Coresight CPU debug nodes for Juno r0, r1 & r2.

We can enable debugging with two methods, adding parameters into kernel
command line for build-in module:
  coresight_cpu_debug.enable=1

Or we can wait the system has booted up to use debugfs nodes to enable
debugging:
  # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable

As result we can get below log after input command:
echo c > /proc/sysrq-trigger:

ARM external debug module:
coresight-cpu-debug 85.debug: CPU[0]:
coresight-cpu-debug 85.debug:  EDPRSR:  0001 (Power:On DLK:Unlock)
coresight-cpu-debug 85.debug:  EDPCSR:  [] 
handle_IPI+0x174/0x1d8
coresight-cpu-debug 85.debug:  EDCIDSR: 
coresight-cpu-debug 85.debug:  EDVIDSR: 9000 (State:Non-secure 
Mode:EL1/0 Width:64bits VMID:0)
coresight-cpu-debug 852000.debug: CPU[1]:
coresight-cpu-debug 852000.debug:  EDPRSR:  0001 (Power:On DLK:Unlock)
coresight-cpu-debug 852000.debug:  EDPCSR:  [] 
debug_notifier_call+0x23c/0x358
coresight-cpu-debug 852000.debug:  EDCIDSR: 
coresight-cpu-debug 852000.debug:  EDVIDSR: 9000 (State:Non-secure 
Mode:EL1/0 Width:64bits VMID:0)


[...]

Changes from v9:
* Used dev_xyz() to replace pr_xyz() for print log.
* Added DT binding patch for Juno shared by Suzuki.

Changes from v8:
* According to Mathieu suggestions to split the doc into two patches,
  one is for kernel parameter and another is for driver documentation.
* Add file entries to MAINTAINERS.
* According to Mathieu suggestions, refined functions
  debug_enable_func()/debug_disable_func().

Changes from v7:
* Fix operator priority bug.
* Minor sequence adjustment for function debug_func_exit().

Changes from v6:
* According to Suzuki and Mathieu suggestions, refined debug module
  driver to install panic notifier when insmod module; refined function
  debug_force_cpu_powered_up() for CPU power state checking; some minor
  fixing for output log, adding comments for memory barrier, code
  alignment.

Changes from v5:
* According to Suzuki and Mathieu suggestions, refined debug module
  driver to drop unused structure members, refactored initialization
  code to distinguish hardware implementation features, refactored
  flow for forcing CPU powered up, supported pm_runtime operations.
* Added one new doc file: Documentation/trace/coresight-cpu-debug.txt,
  which is used to describe detailed info for implementation, clock
  and power domain impaction on debug module, and exmaples for common
  usage.
* Removed "idle constraints" from debug driver.

Changes from v4:
* This version is mainly credit to ARM colleagues many contribution
  ideas for better quality (Thanks a lot Suzuki, Mike and Sudeep!).
* According to Suzuki suggestion, refined debug module driver to avoid
  memory leak for drvdata struct, handle PCSAMPLE_MODE=1, use flag
  drvdata.pc_has_offset to indicate if PCSR has offset, minor fixes.
* According to Mathieu suggestion, refined dt binding description.
* Changed driver to support module mode;
* According to Mike suggestion and very appreciate the pseudo code,
  added support to force CPU powered up with register EDPRCR;
* According to discussions, added command line and debugfs nodes to
  support enabling debugging for boot time, or later can dynamically
  enable/disable debugging by debugfs.
* 

[PATCH v10 02/10] doc: Add documentation for Coresight CPU debug

[Leo Yan]

Add detailed documentation for Coresight CPU debug driver, which
contains the info for driver implementation, Mike Leach excellent
summary for "clock and power domain". At the end some examples on how
to enable the debugging functionality are provided.

Suggested-by: Mike Leach 
Reviewed-by: Mathieu Poirier 
Signed-off-by: Leo Yan 
---
 Documentation/trace/coresight-cpu-debug.txt | 174 
 1 file changed, 174 insertions(+)
 create mode 100644 Documentation/trace/coresight-cpu-debug.txt

diff --git a/Documentation/trace/coresight-cpu-debug.txt 
b/Documentation/trace/coresight-cpu-debug.txt
new file mode 100644
index 000..f0c3f0f
--- /dev/null
+++ b/Documentation/trace/coresight-cpu-debug.txt
@@ -0,0 +1,174 @@
+   Coresight CPU Debug Module
+   ==
+
+   Author:   Leo Yan 
+   Date: April 5th, 2017
+
+Introduction
+
+
+Coresight CPU debug module is defined in ARMv8-a architecture reference manual
+(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
+debug module and it is mainly used for two modes: self-hosted debug and
+external debug. Usually the external debug mode is well known as the external
+debugger connects with SoC from JTAG port; on the other hand the program can
+explore debugging method which rely on self-hosted debug mode, this document
+is to focus on this part.
+
+The debug module provides sample-based profiling extension, which can be used
+to sample CPU program counter, secure state and exception level, etc; usually
+every CPU has one dedicated debug module to be connected. Based on self-hosted
+debug mechanism, Linux kernel can access these related registers from mmio
+region when the kernel panic happens. The callback notifier for kernel panic
+will dump related registers for every CPU; finally this is good for assistant
+analysis for panic.
+
+
+Implementation
+--
+
+- During driver registration, use EDDEVID and EDDEVID1 two device ID
+  registers to decide if sample-based profiling is implemented or not. On some
+  platforms this hardware feature is fully or partialy implemented; and if
+  this feature is not supported then registration will fail.
+
+- When write this doc, the debug driver mainly relies on three sampling
+  registers. The kernel panic callback notifier gathers info from EDPCSR
+  EDVIDSR and EDCIDSR; from EDPCSR we can get program counter, EDVIDSR has
+  information for secure state, exception level, bit width, etc; EDCIDSR is
+  context ID value which contains the sampled value of CONTEXTIDR_EL1.
+
+- The driver supports CPU running mode with either AArch64 or AArch32. The
+  registers naming convention is a bit different between them, AArch64 uses
+  'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
+  'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
+  use AArch64 naming convention.
+
+- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
+  register bits definition. So the driver consolidates two difference:
+
+  If PCSROffset=0b, on ARMv8-a the feature of EDPCSR is not implemented;
+  but ARMv7-a defines "PCSR samples are offset by a value that depends on the
+  instruction set state". For ARMv7-a, the driver checks furthermore if CPU
+  runs with ARM or thumb instruction set and calibrate PCSR value, the
+  detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
+  C11.11.34 "DBGPCSR, Program Counter Sampling Register".
+
+  If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
+  no offset applied and do not sample the instruction set state in AArch32
+  state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
+  in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
+  state EDPCSR is sampled and no offset are applied.
+
+
+Clock and power domain
+--
+
+Before accessing debug registers, we should ensure the clock and power domain
+have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
+Debug registers', the debug registers are spread into two domains: the debug
+domain and the CPU domain.
+
++---+
+|   |
+|   |
+ +--+--+|
+  dbg_clk -->|  |**||<-- cpu_clk
+ |Debug |**|   CPU  |
+   dbg_pd -->|  |**||<-- cpu_pd
+ +--+--+|
+|   |
+|   |
++---+
+
+For debug domain, the user uses DT binding "clocks" and "power-domains" to
+specify the 

Re: [PATCH] kexec/kdump: Minor Documentation updates for arm64 and Image

[AKASHI Takahiro]

On Thu, May 18, 2017 at 01:59:14PM +0800, Dave Young wrote:
> Add Takahiro and Pratyush, they should be able to review the arm64 part.
> 
> On 05/18/17 at 11:03am, Bharat Bhushan wrote:
> > This patch have minor updates in Documentation for arm64i as
> > relocatable kernel.
> > Also this patch updates documentation for using uncompressed
> > image "Image" which is used for ARM64.
> > 
> > Signed-off-by: Bharat Bhushan 
> > ---
> >  Documentation/kdump/kdump.txt | 10 --
> >  1 file changed, 8 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
> > index 615434d..522ce13 100644
> > --- a/Documentation/kdump/kdump.txt
> > +++ b/Documentation/kdump/kdump.txt
> > @@ -112,8 +112,8 @@ There are two possible methods of using Kdump.
> >  2) Or use the system kernel binary itself as dump-capture kernel and there 
> > is
> > no need to build a separate dump-capture kernel. This is possible
> > only with the architectures which support a relocatable kernel. As
> > -   of today, i386, x86_64, ppc64, ia64 and arm architectures support 
> > relocatable
> > -   kernel.
> > +   of today, i386, x86_64, ppc64, ia64, arm and arm64 architectures support
> > +   relocatable kernel.
> >  
> >  Building a relocatable kernel is advantageous from the point of view that
> >  one does not have to build a second kernel for capturing the dump. But
> > @@ -361,6 +361,12 @@ to load dump-capture kernel.
> > --dtb= \
> > --append="root= "
> >  
> > +If you are using a uncompressed Image, then use following command
> 
> s/a/an
> 
> > +to load dump-capture kernel.
> > +
> > +   kexec -p  \
> > +   --initrd= \
> > +   --append="root= "
> 
> For uncompressed Image, dtb is not necessary?

Just for clarification, dtb is optional for both vmlinux and Image
on arm64. (This means you can specify it if you want.)
But this is also true for initrd and append(command line) to some extent.

More precisely, whether these parameters are optional or not will
depend on architectures, not formats, I believe.

Thanks,
-Takahiro AKASHI

> >  
> >  Please note, that --args-linux does not need to be specified for ia64.
> >  It is planned to make this a no-op on that architecture, but for now
> > -- 
> > 1.9.3
> > 
> 
> Thanks
> Dave
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 03/31] btmrvl.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 the right notation for titles;
- Use a list for image names;
- Use literal blocks where needed;
- Whitespace fixes.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/btmrvl.txt | 64 +---
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/Documentation/btmrvl.txt b/Documentation/btmrvl.txt
index 34916a46c099..575512415c2b 100644
--- a/Documentation/btmrvl.txt
+++ b/Documentation/btmrvl.txt
@@ -1,18 +1,15 @@
-===
-   README for btmrvl driver
-===
-
+btmrvl driver
+=
 
 All commands are used via debugfs interface.
 
-=
-Set/get driver configurations:
+Set/get driver configurations
+=
 
 Path:  /debug/btmrvl/config/
 
-gpiogap=[n]
-hscfgcmd
-   These commands are used to configure the host sleep parameters.
+gpiogap=[n], hscfgcmd
+   These commands are used to configure the host sleep parameters::
bit 8:0  -- Gap
bit 16:8 -- GPIO
 
@@ -23,7 +20,8 @@ hscfgcmd
where Gap is the gap in milli seconds between wakeup signal and
wakeup event, or 0xff for special host sleep setting.
 
-   Usage:
+   Usage::
+
# Use SDIO interface to wake up the host and set GAP to 0x80:
echo 0xff80 > /debug/btmrvl/config/gpiogap
echo 1 > /debug/btmrvl/config/hscfgcmd
@@ -32,15 +30,16 @@ hscfgcmd
echo 0x03ff >  /debug/btmrvl/config/gpiogap
echo 1 > /debug/btmrvl/config/hscfgcmd
 
-psmode=[n]
-pscmd
+psmode=[n], pscmd
These commands are used to enable/disable auto sleep mode
 
-   where the option is:
+   where the option is::
+
1   -- Enable auto sleep mode
0   -- Disable auto sleep mode
 
-   Usage:
+   Usage::
+
# Enable auto sleep mode
echo 1 > /debug/btmrvl/config/psmode
echo 1 > /debug/btmrvl/config/pscmd
@@ -50,15 +49,16 @@ pscmd
echo 1 > /debug/btmrvl/config/pscmd
 
 
-hsmode=[n]
-hscmd
+hsmode=[n], hscmd
These commands are used to enable host sleep or wake up firmware
 
-   where the option is:
+   where the option is::
+
1   -- Enable host sleep
0   -- Wake up firmware
 
-   Usage:
+   Usage::
+
# Enable host sleep
echo 1 > /debug/btmrvl/config/hsmode
echo 1 > /debug/btmrvl/config/hscmd
@@ -68,12 +68,13 @@ hscmd
echo 1 > /debug/btmrvl/config/hscmd
 
 
-==
-Get driver status:
+Get driver status
+=
 
 Path:  /debug/btmrvl/status/
 
-Usage:
+Usage::
+
cat /debug/btmrvl/status/
 
 where the args are:
@@ -90,14 +91,17 @@ hsstate
 txdnldrdy
This command displays the value of Tx download ready flag.
 
-
-=
+Issuing a raw hci command
+=
 
 Use hcitool to issue raw hci command, refer to hcitool manual
 
-   Usage: Hcitool cmd   [Parameters]
+Usage::
+
+   Hcitool cmd   [Parameters]
+
+Interface Control Command::
 
-   Interface Control Command
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x00--Enable All interface
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x01--Enable Wlan interface
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x02--Enable BT interface
@@ -105,13 +109,13 @@ Use hcitool to issue raw hci command, refer to hcitool 
manual
hcitool cmd 0x3f 0x5b 0xf5 0x00 0x01--Disable Wlan interface
hcitool cmd 0x3f 0x5b 0xf5 0x00 0x02--Disable BT interface
 
-===
+SD8688 firmware
+===
 
+Images:
 
-SD8688 firmware:
-
-/lib/firmware/sd8688_helper.bin
-/lib/firmware/sd8688.bin
+- /lib/firmware/sd8688_helper.bin
+- /lib/firmware/sd8688.bin
 
 
 The images can be downloaded from:
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 17/31] DMA-ISA-LPC.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 proper markups for titles;
- use :Author: for authorship;
- identify the literal blocks.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DMA-ISA-LPC.txt | 71 ++-
 1 file changed, 36 insertions(+), 35 deletions(-)

diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt
index c41331398752..c44be1a2176f 100644
--- a/Documentation/DMA-ISA-LPC.txt
+++ b/Documentation/DMA-ISA-LPC.txt
@@ -1,19 +1,20 @@
-DMA with ISA and LPC devices
-
+
+DMA with ISA and LPC devices
+
 
-  Pierre Ossman 
+:Author: Pierre Ossman 
 
 This document describes how to do DMA transfers using the old ISA DMA
 controller. Even though ISA is more or less dead today the LPC bus
 uses the same DMA system so it will be around for quite some time.
 
-Part I - Headers and dependencies
--
+Headers and dependencies
+
 
-To do ISA style DMA you need to include two headers:
+To do ISA style DMA you need to include two headers::
 
-#include 
-#include 
+   #include 
+   #include 
 
 The first is the generic DMA API used to convert virtual addresses to
 bus addresses (see Documentation/DMA-API.txt for details).
@@ -23,8 +24,8 @@ this is not present on all platforms make sure you construct 
your
 Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
 to build your driver on unsupported platforms.
 
-Part II - Buffer allocation

+Buffer allocation
+-
 
 The ISA DMA controller has some very strict requirements on which
 memory it can access so extra care must be taken when allocating
@@ -47,8 +48,8 @@ __GFP_REPEAT and __GFP_NOWARN to make the allocator try a bit 
harder.
 (This scarcity also means that you should allocate the buffer as
 early as possible and not release it until the driver is unloaded.)
 
-Part III - Address translation
---
+Address translation
+---
 
 To translate the virtual address to a bus address, use the normal DMA
 API. Do _not_ use isa_virt_to_phys() even though it does the same
@@ -61,8 +62,8 @@ Note: x86_64 had a broken DMA API when it came to ISA but has 
since
 been fixed. If your arch has problems then fix the DMA API instead of
 reverting to the ISA functions.
 
-Part IV - Channels
---
+Channels
+
 
 A normal ISA DMA controller has 8 channels. The lower four are for
 8-bit transfers and the upper four are for 16-bit transfers.
@@ -80,8 +81,8 @@ The ability to use 16-bit or 8-bit transfers is _not_ up to 
you as a
 driver author but depends on what the hardware supports. Check your
 specs or test different channels.
 
-Part V - Transfer data
---
+Transfer data
+-
 
 Now for the good stuff, the actual DMA transfer. :)
 
@@ -112,37 +113,37 @@ Once the DMA transfer is finished (or timed out) you 
should disable
 the channel again. You should also check get_dma_residue() to make
 sure that all data has been transferred.
 
-Example:
+Example::
 
-int flags, residue;
+   int flags, residue;
 
-flags = claim_dma_lock();
+   flags = claim_dma_lock();
 
-clear_dma_ff();
+   clear_dma_ff();
 
-set_dma_mode(channel, DMA_MODE_WRITE);
-set_dma_addr(channel, phys_addr);
-set_dma_count(channel, num_bytes);
+   set_dma_mode(channel, DMA_MODE_WRITE);
+   set_dma_addr(channel, phys_addr);
+   set_dma_count(channel, num_bytes);
 
-dma_enable(channel);
+   dma_enable(channel);
 
-release_dma_lock(flags);
+   release_dma_lock(flags);
 
-while (!device_done());
+   while (!device_done());
 
-flags = claim_dma_lock();
+   flags = claim_dma_lock();
 
-dma_disable(channel);
+   dma_disable(channel);
 
-residue = dma_get_residue(channel);
-if (residue != 0)
-   printk(KERN_ERR "driver: Incomplete DMA transfer!"
-   " %d bytes left!\n", residue);
+   residue = dma_get_residue(channel);
+   if (residue != 0)
+   printk(KERN_ERR "driver: Incomplete DMA transfer!"
+   " %d bytes left!\n", residue);
 
-release_dma_lock(flags);
+   release_dma_lock(flags);
 
-Part VI - Suspend/resume
-
+Suspend/resume
+--
 
 It is the driver's responsibility to make sure that the machine isn't
 suspended while a DMA transfer is in progress. Also, all DMA settings
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  

[PATCH 04/31] bus-virt-phys-mapping.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:

- Move author info to the beginning of file and use :Author:
- use warning/note annotation;
- mark literal blocks as such;
- Add a title for the document;
- use **emphasis** instead of _emphasis_.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/bus-virt-phys-mapping.txt | 63 +++--
 1 file changed, 37 insertions(+), 26 deletions(-)

diff --git a/Documentation/bus-virt-phys-mapping.txt 
b/Documentation/bus-virt-phys-mapping.txt
index 2bc55ff3b4d1..26918b64bd6b 100644
--- a/Documentation/bus-virt-phys-mapping.txt
+++ b/Documentation/bus-virt-phys-mapping.txt
@@ -1,17 +1,26 @@
-[ NOTE: The virt_to_bus() and bus_to_virt() functions have been
+How to access I/O mapped memory from within device drivers
+==
+
+:Author: Linus
+
+.. warning::
+
+   The virt_to_bus() and bus_to_virt() functions have been
superseded by the functionality provided by the PCI DMA interface
(see Documentation/DMA-API-HOWTO.txt).  They continue
to be documented below for historical purposes, but new code
-   must not use them. --davidm 00/12/12 ]
+   must not use them. --davidm 00/12/12
 
-[ This is a mail message in response to a query on IO mapping, thus the
-  strange format for a "document" ]
+::
+
+  [ This is a mail message in response to a query on IO mapping, thus the
+strange format for a "document" ]
 
 The AHA-1542 is a bus-master device, and your patch makes the driver give the
 controller the physical address of the buffers, which is correct on x86
 (because all bus master devices see the physical memory mappings directly). 
 
-However, on many setups, there are actually _three_ different ways of looking
+However, on many setups, there are actually **three** different ways of looking
 at memory addresses, and in this case we actually want the third, the
 so-called "bus address". 
 
@@ -38,7 +47,7 @@ because the memory and the devices share the same address 
space, and that is
 not generally necessarily true on other PCI/ISA setups. 
 
 Now, just as an example, on the PReP (PowerPC Reference Platform), the 
-CPU sees a memory map something like this (this is from memory):
+CPU sees a memory map something like this (this is from memory)::
 
0-2 GB  "real memory"
2 GB-3 GB   "system IO" (inb/out and similar accesses on x86)
@@ -52,7 +61,7 @@ So when the CPU wants any bus master to write to physical 
memory 0, it
 has to give the master address 0x8000 as the memory address.
 
 So, for example, depending on how the kernel is actually mapped on the 
-PPC, you can end up with a setup like this:
+PPC, you can end up with a setup like this::
 
  physical address: 0
  virtual address:  0xC000
@@ -61,7 +70,7 @@ PPC, you can end up with a setup like this:
 where all the addresses actually point to the same thing.  It's just seen 
 through different translations..
 
-Similarly, on the Alpha, the normal translation is
+Similarly, on the Alpha, the normal translation is::
 
  physical address: 0
  virtual address:  0xfc00
@@ -70,7 +79,7 @@ Similarly, on the Alpha, the normal translation is
 (but there are also Alphas where the physical address and the bus address
 are the same). 
 
-Anyway, the way to look up all these translations, you do
+Anyway, the way to look up all these translations, you do::
 
#include 
 
@@ -81,8 +90,8 @@ Anyway, the way to look up all these translations, you do
 
 Now, when do you need these?
 
-You want the _virtual_ address when you are actually going to access that 
-pointer from the kernel. So you can have something like this:
+You want the **virtual** address when you are actually going to access that
+pointer from the kernel. So you can have something like this::
 
/*
 * this is the hardware "mailbox" we use to communicate with
@@ -104,7 +113,7 @@ pointer from the kernel. So you can have something like 
this:
...
 
 on the other hand, you want the bus address when you have a buffer that 
-you want to give to the controller:
+you want to give to the controller::
 
/* ask the controller to read the sense status into "sense_buffer" */
mbox.bufstart = virt_to_bus(_buffer);
@@ -112,7 +121,7 @@ you want to give to the controller:
mbox.status = 0;
notify_controller();
 
-And you generally _never_ want to use the physical address, because you can't
+And you generally **never** want to use the physical address, because you can't
 use that from the CPU (the CPU only uses translated virtual addresses), and
 you can't use it from the bus master. 
 
@@ -124,8 +133,10 @@ be remapped as measured in units of pages, 

[PATCH 16/31] DMA-attributes.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 file is almost on the standard format. All it needs
to be parsed by Sphinx is to fix its main title and add
a few blank lines.

Yet, it is worth to replace NOTE: by the corresponding
ReST markup.

While here, remove the extra "---" from a subtitle.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DMA-attributes.txt | 15 +--
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt
index 44c6bc496eee..8f8d97f65d73 100644
--- a/Documentation/DMA-attributes.txt
+++ b/Documentation/DMA-attributes.txt
@@ -1,5 +1,6 @@
-   DMA attributes
-   ==
+==
+DMA attributes
+==
 
 This document describes the semantics of the DMA attributes that are
 defined in linux/dma-mapping.h.
@@ -108,6 +109,7 @@ This is a hint to the DMA-mapping subsystem that it's 
probably not worth
 the time to try to allocate memory to in a way that gives better TLB
 efficiency (AKA it's not worth trying to build the mapping out of larger
 pages).  You might want to specify this if:
+
 - You know that the accesses to this memory won't thrash the TLB.
   You might know that the accesses are likely to be sequential or
   that they aren't sequential but it's unlikely you'll ping-pong
@@ -121,11 +123,12 @@ pages).  You might want to specify this if:
   the mapping to have a short lifetime then it may be worth it to
   optimize allocation (avoid coming up with large pages) instead of
   getting the slight performance win of larger pages.
+
 Setting this hint doesn't guarantee that you won't get huge pages, but it
 means that we won't try quite as hard to get them.
 
-NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,
-though ARM64 patches will likely be posted soon.
+.. note:: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,
+ though ARM64 patches will likely be posted soon.
 
 DMA_ATTR_NO_WARN
 
@@ -142,10 +145,10 @@ problem at all, depending on the implementation of the 
retry mechanism.
 So, this provides a way for drivers to avoid those error messages on calls
 where allocation failures are not a problem, and shouldn't bother the logs.
 
-NOTE: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.
+.. note:: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.
 
 DMA_ATTR_PRIVILEGED
---
+---
 
 Some advanced peripherals such as remote processors and GPUs perform
 accesses to DMA buffers in both privileged "supervisor" and unprivileged
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 11/31] crc32.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.

While here, replace a comma by a dot at the end of a paragraph.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/crc32.txt | 75 +++--
 1 file changed, 41 insertions(+), 34 deletions(-)

diff --git a/Documentation/crc32.txt b/Documentation/crc32.txt
index a08a7dd9d625..8a6860f33b4e 100644
--- a/Documentation/crc32.txt
+++ b/Documentation/crc32.txt
@@ -1,4 +1,6 @@
-A brief CRC tutorial.
+=
+brief tutorial on CRC computation
+=
 
 A CRC is a long-division remainder.  You add the CRC to the message,
 and the whole thing (message+CRC) is a multiple of the given
@@ -8,7 +10,8 @@ remainder computed on the message+CRC is 0.  This latter 
approach
 is used by a lot of hardware implementations, and is why so many
 protocols put the end-of-frame flag after the CRC.
 
-It's actually the same long division you learned in school, except that
+It's actually the same long division you learned in school, except that:
+
 - We're working in binary, so the digits are only 0 and 1, and
 - When dividing polynomials, there are no carries.  Rather than add and
   subtract, we just xor.  Thus, we tend to get a bit sloppy about
@@ -40,11 +43,12 @@ throw the quotient bit away, but subtract the appropriate 
multiple of
 the polynomial from the remainder and we're back to where we started,
 ready to process the next bit.
 
-A big-endian CRC written this way would be coded like:
-for (i = 0; i < input_bits; i++) {
-   multiple = remainder & 0x8000 ? CRCPOLY : 0;
-   remainder = (remainder << 1 | next_input_bit()) ^ multiple;
-}
+A big-endian CRC written this way would be coded like::
+
+   for (i = 0; i < input_bits; i++) {
+   multiple = remainder & 0x8000 ? CRCPOLY : 0;
+   remainder = (remainder << 1 | next_input_bit()) ^ multiple;
+   }
 
 Notice how, to get at bit 32 of the shifted remainder, we look
 at bit 31 of the remainder *before* shifting it.
@@ -54,25 +58,26 @@ the remainder don't actually affect any decision-making 
until
 32 bits later.  Thus, the first 32 cycles of this are pretty boring.
 Also, to add the CRC to a message, we need a 32-bit-long hole for it at
 the end, so we have to add 32 extra cycles shifting in zeros at the
-end of every message,
+end of every message.
 
 These details lead to a standard trick: rearrange merging in the
 next_input_bit() until the moment it's needed.  Then the first 32 cycles
 can be precomputed, and merging in the final 32 zero bits to make room
-for the CRC can be skipped entirely.  This changes the code to:
+for the CRC can be skipped entirely.  This changes the code to::
 
-for (i = 0; i < input_bits; i++) {
-   remainder ^= next_input_bit() << 31;
-   multiple = (remainder & 0x8000) ? CRCPOLY : 0;
-   remainder = (remainder << 1) ^ multiple;
-}
+   for (i = 0; i < input_bits; i++) {
+   remainder ^= next_input_bit() << 31;
+   multiple = (remainder & 0x8000) ? CRCPOLY : 0;
+   remainder = (remainder << 1) ^ multiple;
+   }
 
-With this optimization, the little-endian code is particularly simple:
-for (i = 0; i < input_bits; i++) {
-   remainder ^= next_input_bit();
-   multiple = (remainder & 1) ? CRCPOLY : 0;
-   remainder = (remainder >> 1) ^ multiple;
-}
+With this optimization, the little-endian code is particularly simple::
+
+   for (i = 0; i < input_bits; i++) {
+   remainder ^= next_input_bit();
+   multiple = (remainder & 1) ? CRCPOLY : 0;
+   remainder = (remainder >> 1) ^ multiple;
+   }
 
 The most significant coefficient of the remainder polynomial is stored
 in the least significant bit of the binary "remainder" variable.
@@ -81,23 +86,25 @@ be bit-reversed) and next_input_bit().
 
 As long as next_input_bit is returning the bits in a sensible order, we don't
 *have* to wait until the last possible moment to merge in additional bits.
-We can do it 8 bits at a time rather than 1 bit at a time:
-for (i = 0; i < input_bytes; i++) {
-   remainder ^= next_input_byte() << 24;
-   for (j = 0; j < 8; j++) {
-   multiple = (remainder & 0x8000) ? CRCPOLY : 0;
-   remainder = (remainder << 1) ^ multiple;
+We can do it 8 bits at a time rather than 1 bit at a time::
+
+   for (i = 0; i < input_bytes; i++) {
+   remainder ^= next_input_byte() << 24;
+   for (j = 0; j < 8; j++) {
+   multiple = (remainder & 0x8000) ? CRCPOLY : 0;
+   remainder = (remainder << 1) ^ multiple;
+   }
}
-}
 
-Or 

[PATCH 21/31] flexible-arrays.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 :Author: and :Updated: markups;
- use proper markup for the document title;
- mark the literal-blocks.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/flexible-arrays.txt | 24 +---
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/Documentation/flexible-arrays.txt 
b/Documentation/flexible-arrays.txt
index df904aec9904..45aec4d354f7 100644
--- a/Documentation/flexible-arrays.txt
+++ b/Documentation/flexible-arrays.txt
@@ -1,6 +1,8 @@
 Using flexible arrays in the kernel
-Last updated for 2.6.32
-Jonathan Corbet 
+===
+
+:Updated: Last updated for 2.6.32
+:Author: Jonathan Corbet 
 
 Large contiguous memory allocations can be unreliable in the Linux kernel.
 Kernel programmers will sometimes respond to this problem by allocating
@@ -26,7 +28,7 @@ operation.  It's also worth noting that flexible arrays do no 
internal
 locking at all; if concurrent access to an array is possible, then the
 caller must arrange for appropriate mutual exclusion.
 
-The creation of a flexible array is done with:
+The creation of a flexible array is done with::
 
 #include 
 
@@ -40,14 +42,14 @@ argument is passed directly to the internal memory 
allocation calls.  With
 the current code, using flags to ask for high memory is likely to lead to
 notably unpleasant side effects.
 
-It is also possible to define flexible arrays at compile time with:
+It is also possible to define flexible arrays at compile time with::
 
 DEFINE_FLEX_ARRAY(name, element_size, total);
 
 This macro will result in a definition of an array with the given name; the
 element size and total will be checked for validity at compile time.
 
-Storing data into a flexible array is accomplished with a call to:
+Storing data into a flexible array is accomplished with a call to::
 
 int flex_array_put(struct flex_array *array, unsigned int element_nr,
   void *src, gfp_t flags);
@@ -63,7 +65,7 @@ running in some sort of atomic context; in this situation, 
sleeping in the
 memory allocator would be a bad thing.  That can be avoided by using
 GFP_ATOMIC for the flags value, but, often, there is a better way.  The
 trick is to ensure that any needed memory allocations are done before
-entering atomic context, using:
+entering atomic context, using::
 
 int flex_array_prealloc(struct flex_array *array, unsigned int start,
unsigned int nr_elements, gfp_t flags);
@@ -73,7 +75,7 @@ defined by start and nr_elements has been allocated.  
Thereafter, a
 flex_array_put() call on an element in that range is guaranteed not to
 block.
 
-Getting data back out of the array is done with:
+Getting data back out of the array is done with::
 
 void *flex_array_get(struct flex_array *fa, unsigned int element_nr);
 
@@ -89,7 +91,7 @@ involving that number probably result from use of unstored 
array entries.
 Note that, if array elements are allocated with __GFP_ZERO, they will be
 initialized to zero and this poisoning will not happen.
 
-Individual elements in the array can be cleared with:
+Individual elements in the array can be cleared with::
 
 int flex_array_clear(struct flex_array *array, unsigned int element_nr);
 
@@ -97,7 +99,7 @@ This function will set the given element to FLEX_ARRAY_FREE 
and return
 zero.  If storage for the indicated element is not allocated for the array,
 flex_array_clear() will return -EINVAL instead.  Note that clearing an
 element does not release the storage associated with it; to reduce the
-allocated size of an array, call:
+allocated size of an array, call::
 
 int flex_array_shrink(struct flex_array *array);
 
@@ -106,12 +108,12 @@ This function works by scanning the array for pages 
containing nothing but
 FLEX_ARRAY_FREE bytes, so (1) it can be expensive, and (2) it will not work
 if the array's pages are allocated with __GFP_ZERO.
 
-It is possible to remove all elements of an array with a call to:
+It is possible to remove all elements of an array with a call to::
 
 void flex_array_free_parts(struct flex_array *array);
 
 This call frees all elements, but leaves the array itself in place.
-Freeing the entire array is done with:
+Freeing the entire array is done with::
 
 void flex_array_free(struct flex_array *array);
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 05/31] cachetlb.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 the title format;
- use :Author: for author's name;
- mark literals as such;
- use note and important notation.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/cachetlb.txt | 92 ++
 1 file changed, 52 insertions(+), 40 deletions(-)

diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt
index 3f9f808b5119..6eb9d3f090cd 100644
--- a/Documentation/cachetlb.txt
+++ b/Documentation/cachetlb.txt
@@ -1,7 +1,8 @@
-   Cache and TLB Flushing
-Under Linux
+==
+Cache and TLB Flushing Under Linux
+==
 
-   David S. Miller 
+:Author: David S. Miller 
 
 This document describes the cache/tlb flushing interfaces called
 by the Linux VM subsystem.  It enumerates over each interface,
@@ -28,7 +29,7 @@ Therefore when software page table changes occur, the kernel 
will
 invoke one of the following flush methods _after_ the page table
 changes occur:
 
-1) void flush_tlb_all(void)
+1) ``void flush_tlb_all(void)``
 
The most severe flush of all.  After this interface runs,
any previous page table modification whatsoever will be
@@ -37,7 +38,7 @@ changes occur:
This is usually invoked when the kernel page tables are
changed, since such translations are "global" in nature.
 
-2) void flush_tlb_mm(struct mm_struct *mm)
+2) ``void flush_tlb_mm(struct mm_struct *mm)``
 
This interface flushes an entire user address space from
the TLB.  After running, this interface must make sure that
@@ -49,8 +50,8 @@ changes occur:
page table operations such as what happens during
fork, and exec.
 
-3) void flush_tlb_range(struct vm_area_struct *vma,
-   unsigned long start, unsigned long end)
+3) ``void flush_tlb_range(struct vm_area_struct *vma,
+   unsigned long start, unsigned long end)``
 
Here we are flushing a specific range of (user) virtual
address translations from the TLB.  After running, this
@@ -69,7 +70,7 @@ changes occur:
call flush_tlb_page (see below) for each entry which may be
modified.
 
-4) void flush_tlb_page(struct vm_area_struct *vma, unsigned long addr)
+4) ``void flush_tlb_page(struct vm_area_struct *vma, unsigned long addr)``
 
This time we need to remove the PAGE_SIZE sized translation
from the TLB.  The 'vma' is the backing structure used by
@@ -87,8 +88,8 @@ changes occur:
 
This is used primarily during fault processing.
 
-5) void update_mmu_cache(struct vm_area_struct *vma,
-unsigned long address, pte_t *ptep)
+5) ``void update_mmu_cache(struct vm_area_struct *vma,
+   unsigned long address, pte_t *ptep)``
 
At the end of every page fault, this routine is invoked to
tell the architecture specific code that a translation
@@ -100,7 +101,7 @@ changes occur:
translations for software managed TLB configurations.
The sparc64 port currently does this.
 
-6) void tlb_migrate_finish(struct mm_struct *mm)
+6) ``void tlb_migrate_finish(struct mm_struct *mm)``
 
This interface is called at the end of an explicit
process migration. This interface provides a hook
@@ -112,7 +113,7 @@ changes occur:
 
 Next, we have the cache flushing interfaces.  In general, when Linux
 is changing an existing virtual-->physical mapping to a new value,
-the sequence will be in one of the following forms:
+the sequence will be in one of the following forms::
 
1) flush_cache_mm(mm);
   change_all_page_tables_of(mm);
@@ -143,7 +144,7 @@ and have no dependency on translation information.
 
 Here are the routines, one by one:
 
-1) void flush_cache_mm(struct mm_struct *mm)
+1) ``void flush_cache_mm(struct mm_struct *mm)``
 
This interface flushes an entire user address space from
the caches.  That is, after running, there will be no cache
@@ -152,7 +153,7 @@ Here are the routines, one by one:
This interface is used to handle whole address space
page table operations such as what happens during exit and exec.
 
-2) void flush_cache_dup_mm(struct mm_struct *mm)
+2) ``void flush_cache_dup_mm(struct mm_struct *mm)``
 
This interface flushes an entire user address space from
the caches.  That is, after running, there will be no cache
@@ -164,8 +165,8 @@ Here are the routines, one by one:
This option is separate from flush_cache_mm to allow some
optimizations for VIPT caches.
 
-3) void flush_cache_range(struct vm_area_struct *vma,
- unsigned long start, unsigned long end)
+3) ``void 

[PATCH 15/31] DMA-API-HOWTO.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;
- Mark some literals that would otherwise produce warnings;
- Mark authorship.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DMA-API-HOWTO.txt | 159 +++-
 1 file changed, 92 insertions(+), 67 deletions(-)

diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index 979228bc9035..7c0a0ae4ab83 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -1,22 +1,24 @@
-Dynamic DMA mapping Guide
-=
+=
+Dynamic DMA mapping Guide
+=
 
-David S. Miller 
-Richard Henderson 
- Jakub Jelinek 
+:Author: David S. Miller 
+:Author: Richard Henderson 
+:Author: Jakub Jelinek 
 
 This is a guide to device driver writers on how to use the DMA API
 with example pseudo-code.  For a concise description of the API, see
 DMA-API.txt.
 
-   CPU and DMA addresses
+CPU and DMA addresses
+=
 
 There are several kinds of addresses involved in the DMA API, and it's
 important to understand the differences.
 
 The kernel normally uses virtual addresses.  Any address returned by
 kmalloc(), vmalloc(), and similar interfaces is a virtual address and can
-be stored in a "void *".
+be stored in a ``void *``.
 
 The virtual memory system (TLB, page tables, etc.) translates virtual
 addresses to CPU physical addresses, which are stored as "phys_addr_t" or
@@ -37,7 +39,7 @@ be restricted to a subset of that space.  For example, even 
if a system
 supports 64-bit addresses for main memory and PCI BARs, it may use an IOMMU
 so devices only need to use 32-bit DMA addresses.
 
-Here's a picture and some examples:
+Here's a picture and some examples::
 
CPU  CPU  Bus
  Virtual  Physical Address
@@ -98,15 +100,16 @@ microprocessor architecture. You should use the DMA API 
rather than the
 bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the
 pci_map_*() interfaces.
 
-First of all, you should make sure
+First of all, you should make sure::
 
-#include 
+   #include 
 
 is in your driver, which provides the definition of dma_addr_t.  This type
 can hold any valid DMA address for the platform and should be used
 everywhere you hold a DMA address returned from the DMA mapping functions.
 
-What memory is DMA'able?
+What memory is DMA'able?
+
 
 The first piece of information you must know is what kernel memory can
 be used with the DMA mapping facilities.  There has been an unwritten
@@ -143,7 +146,8 @@ What about block I/O and networking buffers?  The block I/O 
and
 networking subsystems make sure that the buffers they use are valid
 for you to DMA from/to.
 
-   DMA addressing limitations
+DMA addressing limitations
+==
 
 Does your device have any DMA addressing limitations?  For example, is
 your device only capable of driving the low order 24-bits of address?
@@ -166,7 +170,7 @@ style to do this even if your device holds the default 
setting,
 because this shows that you did think about these issues wrt. your
 device.
 
-The query is performed via a call to dma_set_mask_and_coherent():
+The query is performed via a call to dma_set_mask_and_coherent()::
 
int dma_set_mask_and_coherent(struct device *dev, u64 mask);
 
@@ -175,12 +179,12 @@ If you have some special requirements, then the following 
two separate
 queries can be used instead:
 
The query for streaming mappings is performed via a call to
-   dma_set_mask():
+   dma_set_mask()::
 
int dma_set_mask(struct device *dev, u64 mask);
 
The query for consistent allocations is performed via a call
-   to dma_set_coherent_mask():
+   to dma_set_coherent_mask()::
 
int dma_set_coherent_mask(struct device *dev, u64 mask);
 
@@ -209,7 +213,7 @@ of your driver reports that performance is bad or that the 
device is not
 even detected, you can ask them for the kernel messages to find out
 exactly why.
 
-The standard 32-bit addressing device would do something like this:
+The standard 32-bit addressing device would do something like this::
 
if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {
dev_warn(dev, "mydev: No suitable DMA available\n");
@@ -225,7 +229,7 @@ than 64-bit addressing.  For example, Sparc64 PCI SAC 
addressing is
 more 

[PATCH 14/31] DMA-API.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:

- Fix some title marks to match ReST;
- use :Author: for author name;
- foo_ is an hyperlink. Get rid of it;
- Mark literal blocks as such;
- Use tables on some places that are almost using the
  table format.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DMA-API.txt | 575 ++
 1 file changed, 326 insertions(+), 249 deletions(-)

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index 6b20128fab8a..2104686b9f02 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -1,7 +1,7 @@
-   Dynamic DMA mapping using the generic device
-   
+Dynamic DMA mapping using the generic device
+
 
-James E.J. Bottomley 
+:Author: James E.J. Bottomley 
 
 This document describes the DMA API.  For a more gentle introduction
 of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
@@ -12,10 +12,10 @@ machines.  Unless you know that your driver absolutely has 
to support
 non-consistent platforms (this is usually only legacy platforms) you
 should only use the API described in part I.
 
-Part I - dma_ API
--
+Part I - dma_API
+
 
-To get the dma_ API, you must #include .  This
+To get the dma_API, you must #include .  This
 provides dma_addr_t and the interfaces described below.
 
 A dma_addr_t can hold any valid DMA address for the platform.  It can be
@@ -26,9 +26,11 @@ address space and the DMA address space.
 Part Ia - Using large DMA-coherent buffers
 --
 
-void *
-dma_alloc_coherent(struct device *dev, size_t size,
-dma_addr_t *dma_handle, gfp_t flag)
+::
+
+   void *
+   dma_alloc_coherent(struct device *dev, size_t size,
+  dma_addr_t *dma_handle, gfp_t flag)
 
 Consistent memory is memory for which a write by either the device or
 the processor can immediately be read by the processor or device
@@ -51,20 +53,24 @@ consolidate your requests for consistent memory as much as 
possible.
 The simplest way to do that is to use the dma_pool calls (see below).
 
 The flag parameter (dma_alloc_coherent() only) allows the caller to
-specify the GFP_ flags (see kmalloc()) for the allocation (the
+specify the ``GFP_`` flags (see kmalloc()) for the allocation (the
 implementation may choose to ignore flags that affect the location of
 the returned memory, like GFP_DMA).
 
-void *
-dma_zalloc_coherent(struct device *dev, size_t size,
-dma_addr_t *dma_handle, gfp_t flag)
+::
+
+   void *
+   dma_zalloc_coherent(struct device *dev, size_t size,
+   dma_addr_t *dma_handle, gfp_t flag)
 
 Wraps dma_alloc_coherent() and also zeroes the returned memory if the
 allocation attempt succeeded.
 
-void
-dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
-  dma_addr_t dma_handle)
+::
+
+   void
+   dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
+ dma_addr_t dma_handle)
 
 Free a region of consistent memory you previously allocated.  dev,
 size and dma_handle must all be the same as those passed into
@@ -78,7 +84,7 @@ may only be called with IRQs enabled.
 Part Ib - Using small DMA-coherent buffers
 --
 
-To get this part of the dma_ API, you must #include 
+To get this part of the dma_API, you must #include 
 
 Many drivers need lots of small DMA-coherent memory regions for DMA
 descriptors or I/O buffers.  Rather than allocating in units of a page
@@ -88,6 +94,8 @@ not __get_free_pages().  Also, they understand common 
hardware constraints
 for alignment, like queue heads needing to be aligned on N-byte boundaries.
 
 
+::
+
struct dma_pool *
dma_pool_create(const char *name, struct device *dev,
size_t size, size_t align, size_t alloc);
@@ -103,16 +111,21 @@ in bytes, and must be a power of two).  If your device 
has no boundary
 crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
 from this pool must not cross 4KByte boundaries.
 
+::
 
-   void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
- dma_addr_t *handle)
+   void *
+   dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
+   dma_addr_t *handle)
 
 Wraps dma_pool_alloc() and also zeroes the returned memory if the
 allocation attempt succeeded.
 
 
-   void *dma_pool_alloc(struct 

[PATCH 24/31] highuid.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 the title;
- use :Author: and :Last updated: markups at the beginning with
  authorship info;
- use proper markups for the lists.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/highuid.txt | 46 --
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/Documentation/highuid.txt b/Documentation/highuid.txt
index 6bad6f1d1cac..ae024b3fe4ef 100644
--- a/Documentation/highuid.txt
+++ b/Documentation/highuid.txt
@@ -1,4 +1,8 @@
-Notes on the change from 16-bit UIDs to 32-bit UIDs:
+Notes on the change from 16-bit UIDs to 32-bit UIDs
+===
+
+:Author: Chris Wing 
+:Last updated: January 11, 2000
 
 - kernel code MUST take into account __kernel_uid_t and __kernel_uid32_t
   when communicating between user and kernel space in an ioctl or data
@@ -28,30 +32,34 @@ What's left to be done for 32-bit UIDs on all Linux 
architectures:
   uses the 32-bit UID system calls properly otherwise.
 
   This affects at least:
-   iBCS on Intel
 
-   sparc32 emulation on sparc64
-   (need to support whatever new 32-bit UID system calls are added to
-   sparc32)
+   - iBCS on Intel
+
+   - sparc32 emulation on sparc64
+ (need to support whatever new 32-bit UID system calls are added to
+ sparc32)
 
 - Validate that all filesystems behave properly.
 
   At present, 32-bit UIDs _should_ work for:
-   ext2
-   ufs
-   isofs
-   nfs
-   coda
-   udf
+
+   - ext2
+   - ufs
+   - isofs
+   - nfs
+   - coda
+   - udf
 
   Ioctl() fixups have been made for:
-   ncpfs
-   smbfs
+
+   - ncpfs
+   - smbfs
 
   Filesystems with simple fixups to prevent 16-bit UID wraparound:
-   minix
-   sysv
-   qnx4
+
+   - minix
+   - sysv
+   - qnx4
 
   Other filesystems have not been checked yet.
 
@@ -69,9 +77,3 @@ What's left to be done for 32-bit UIDs on all Linux 
architectures:
 - make sure that the UID mapping feature of AX25 networking works properly
   (it should be safe because it's always used a 32-bit integer to
   communicate between user and kernel)
-
-
-Chris Wing
-wi...@umich.edu
-
-last updated: January 11, 2000
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 22/31] futex-requeue-pi.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 level for the document title;
- mark literal blocks.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/futex-requeue-pi.txt | 83 +++---
 1 file changed, 42 insertions(+), 41 deletions(-)

diff --git a/Documentation/futex-requeue-pi.txt 
b/Documentation/futex-requeue-pi.txt
index 77b36f59d16b..14ab5787b9a7 100644
--- a/Documentation/futex-requeue-pi.txt
+++ b/Documentation/futex-requeue-pi.txt
@@ -1,5 +1,6 @@
+
 Futex Requeue PI
-
+
 
 Requeueing of tasks from a non-PI futex to a PI futex requires
 special handling in order to ensure the underlying rt_mutex is never
@@ -20,28 +21,28 @@ implementation would wake the highest-priority waiter, and 
leave the
 rest to the natural wakeup inherent in unlocking the mutex
 associated with the condvar.
 
-Consider the simplified glibc calls:
+Consider the simplified glibc calls::
 
-/* caller must lock mutex */
-pthread_cond_wait(cond, mutex)
-{
-   lock(cond->__data.__lock);
-   unlock(mutex);
-   do {
-  unlock(cond->__data.__lock);
-  futex_wait(cond->__data.__futex);
-  lock(cond->__data.__lock);
-   } while(...)
-   unlock(cond->__data.__lock);
-   lock(mutex);
-}
+   /* caller must lock mutex */
+   pthread_cond_wait(cond, mutex)
+   {
+   lock(cond->__data.__lock);
+   unlock(mutex);
+   do {
+   unlock(cond->__data.__lock);
+   futex_wait(cond->__data.__futex);
+   lock(cond->__data.__lock);
+   } while(...)
+   unlock(cond->__data.__lock);
+   lock(mutex);
+   }
 
-pthread_cond_broadcast(cond)
-{
-   lock(cond->__data.__lock);
-   unlock(cond->__data.__lock);
-   futex_requeue(cond->data.__futex, cond->mutex);
-}
+   pthread_cond_broadcast(cond)
+   {
+   lock(cond->__data.__lock);
+   unlock(cond->__data.__lock);
+   futex_requeue(cond->data.__futex, cond->mutex);
+   }
 
 Once pthread_cond_broadcast() requeues the tasks, the cond->mutex
 has waiters. Note that pthread_cond_wait() attempts to lock the
@@ -53,29 +54,29 @@ In order to support PI-aware pthread_condvar's, the kernel 
needs to
 be able to requeue tasks to PI futexes.  This support implies that
 upon a successful futex_wait system call, the caller would return to
 user space already holding the PI futex.  The glibc implementation
-would be modified as follows:
+would be modified as follows::
 
 
-/* caller must lock mutex */
-pthread_cond_wait_pi(cond, mutex)
-{
-   lock(cond->__data.__lock);
-   unlock(mutex);
-   do {
-  unlock(cond->__data.__lock);
-  futex_wait_requeue_pi(cond->__data.__futex);
-  lock(cond->__data.__lock);
-   } while(...)
-   unlock(cond->__data.__lock);
-/* the kernel acquired the mutex for us */
-}
+   /* caller must lock mutex */
+   pthread_cond_wait_pi(cond, mutex)
+   {
+   lock(cond->__data.__lock);
+   unlock(mutex);
+   do {
+   unlock(cond->__data.__lock);
+   futex_wait_requeue_pi(cond->__data.__futex);
+   lock(cond->__data.__lock);
+   } while(...)
+   unlock(cond->__data.__lock);
+   /* the kernel acquired the mutex for us */
+   }
 
-pthread_cond_broadcast_pi(cond)
-{
-   lock(cond->__data.__lock);
-   unlock(cond->__data.__lock);
-   futex_requeue_pi(cond->data.__futex, cond->mutex);
-}
+   pthread_cond_broadcast_pi(cond)
+   {
+   lock(cond->__data.__lock);
+   unlock(cond->__data.__lock);
+   futex_requeue_pi(cond->data.__futex, cond->mutex);
+   }
 
 The actual glibc implementation will likely test for PI and make the
 necessary changes inside the existing calls rather than creating new
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 08/31] clk.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 section/title markups;
- Use :Author: for authorship;
- Mark literals and literal blocks;
- Mark tables;
- Use ReST notation for footnotes.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/clk.txt | 189 --
 1 file changed, 106 insertions(+), 83 deletions(-)

diff --git a/Documentation/clk.txt b/Documentation/clk.txt
index 22f026aa2f34..be909ed45970 100644
--- a/Documentation/clk.txt
+++ b/Documentation/clk.txt
@@ -1,12 +1,16 @@
-   The Common Clk Framework
-   Mike Turquette 
+
+The Common Clk Framework
+
+
+:Author: Mike Turquette 
 
 This document endeavours to explain the common clk framework details,
 and how to port a platform over to this framework.  It is not yet a
 detailed explanation of the clock api in include/linux/clk.h, but
 perhaps someday it will include that information.
 
-   Part 1 - introduction and interface split
+Introduction and interface split
+
 
 The common clk framework is an interface to control the clock nodes
 available on various devices today.  This may come in the form of clock
@@ -35,10 +39,11 @@ is defined in struct clk_foo and pointed to within struct 
clk_core.  This
 allows for easy navigation between the two discrete halves of the common
 clock interface.
 
-   Part 2 - common data structures and api
+Common data structures and api
+==
 
 Below is the common struct clk_core definition from
-drivers/clk/clk.c, modified for brevity:
+drivers/clk/clk.c, modified for brevity::
 
struct clk_core {
const char  *name;
@@ -59,7 +64,7 @@ struct clk.  That api is documented in include/linux/clk.h.
 
 Platforms and devices utilizing the common struct clk_core use the struct
 clk_ops pointer in struct clk_core to perform the hardware-specific parts of
-the operations defined in clk-provider.h:
+the operations defined in clk-provider.h::
 
struct clk_ops {
int (*prepare)(struct clk_hw *hw);
@@ -95,19 +100,20 @@ the operations defined in clk-provider.h:
  struct dentry *dentry);
};
 
-   Part 3 - hardware clk implementations
+Hardware clk implementations
+
 
 The strength of the common struct clk_core comes from its .ops and .hw pointers
 which abstract the details of struct clk from the hardware-specific bits, and
 vice versa.  To illustrate consider the simple gateable clk implementation in
-drivers/clk/clk-gate.c:
+drivers/clk/clk-gate.c::
 
-struct clk_gate {
-   struct clk_hw   hw;
-   void __iomem*reg;
-   u8  bit_idx;
-   ...
-};
+   struct clk_gate {
+   struct clk_hw   hw;
+   void __iomem*reg;
+   u8  bit_idx;
+   ...
+   };
 
 struct clk_gate contains struct clk_hw hw as well as hardware-specific
 knowledge about which register and bit controls this clk's gating.
@@ -115,7 +121,7 @@ Nothing about clock topology or accounting, such as 
enable_count or
 notifier_count, is needed here.  That is all handled by the common
 framework code and struct clk_core.
 
-Let's walk through enabling this clk from driver code:
+Let's walk through enabling this clk from driver code::
 
struct clk *clk;
clk = clk_get(NULL, "my_gateable_clk");
@@ -123,70 +129,71 @@ Let's walk through enabling this clk from driver code:
clk_prepare(clk);
clk_enable(clk);
 
-The call graph for clk_enable is very simple:
+The call graph for clk_enable is very simple::
 
-clk_enable(clk);
-   clk->ops->enable(clk->hw);
-   [resolves to...]
-   clk_gate_enable(hw);
-   [resolves struct clk gate with to_clk_gate(hw)]
-   clk_gate_set_bit(gate);
+   clk_enable(clk);
+   clk->ops->enable(clk->hw);
+   [resolves to...]
+   clk_gate_enable(hw);
+   [resolves struct clk gate with to_clk_gate(hw)]
+   clk_gate_set_bit(gate);
 
-And the definition of clk_gate_set_bit:
+And the definition of clk_gate_set_bit::
 
-static void clk_gate_set_bit(struct clk_gate *gate)
-{
-   u32 reg;
+   static void clk_gate_set_bit(struct clk_gate *gate)
+   {
+   u32 reg;
 
-   reg = __raw_readl(gate->reg);
-   reg |= BIT(gate->bit_idx);
-   writel(reg, gate->reg);
-}
+   reg = __raw_readl(gate->reg);
+   reg |= BIT(gate->bit_idx);
+   writel(reg, gate->reg);
+   }
 

[PATCH 23/31] gcc-plugins.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 main title;
- use the right markup for footnotes;
- use bold markup for files name;
- identify literal blocks;
- add blank lines to avoid Sphinx to complain;
- remove numeration from titles.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/gcc-plugins.txt | 58 ---
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt
index 433eaefb4aa1..8502f24396fb 100644
--- a/Documentation/gcc-plugins.txt
+++ b/Documentation/gcc-plugins.txt
@@ -1,14 +1,15 @@
+=
 GCC plugin infrastructure
 =
 
 
-1. Introduction
-===
+Introduction
+
 
 GCC plugins are loadable modules that provide extra features to the
-compiler [1]. They are useful for runtime instrumentation and static analysis.
+compiler [1]_. They are useful for runtime instrumentation and static analysis.
 We can analyse, change and add further code during compilation via
-callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5].
+callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
 
 The GCC plugin infrastructure of the kernel supports all gcc versions from
 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
@@ -21,56 +22,61 @@ and versions 4.8+ can only be compiled by a C++ compiler.
 Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
 powerpc architectures.
 
-This infrastructure was ported from grsecurity [6] and PaX [7].
+This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
 
 --
-[1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
-[2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
-[3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
-[4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
-[5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
-[6] https://grsecurity.net/
-[7] https://pax.grsecurity.net/
 
+.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
+.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
+.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
+.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
+.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
+.. [6] https://grsecurity.net/
+.. [7] https://pax.grsecurity.net/
 
-2. Files
-
 
-$(src)/scripts/gcc-plugins
+Files
+=
+
+**$(src)/scripts/gcc-plugins**
+
This is the directory of the GCC plugins.
 
-$(src)/scripts/gcc-plugins/gcc-common.h
+**$(src)/scripts/gcc-plugins/gcc-common.h**
+
This is a compatibility header for GCC plugins.
It should be always included instead of individual gcc headers.
 
-$(src)/scripts/gcc-plugin.sh
+**$(src)/scripts/gcc-plugin.sh**
+
This script checks the availability of the included headers in
gcc-common.h and chooses the proper host compiler to build the plugins
(gcc-4.7 can be built by either gcc or g++).
 
-$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h
+**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
+
These headers automatically generate the registration structures for
GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
from 4.5 to 6.0.
They should be preferred to creating the structures by hand.
 
 
-3. Usage
-
+Usage
+=
 
 You must install the gcc plugin headers for your gcc version,
-e.g., on Ubuntu for gcc-4.9:
+e.g., on Ubuntu for gcc-4.9::
 
apt-get install gcc-4.9-plugin-dev
 
-Enable a GCC plugin based feature in the kernel config:
+Enable a GCC plugin based feature in the kernel config::
 
CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
 
-To compile only the plugin(s):
+To compile only the plugin(s)::
 
make gcc-plugins
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 01/31] bcache.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;
- Use a list for the listed URLs;
- mark literal blocks;
- adjust whitespaces;
- Don't capitalize section titles.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/bcache.txt | 200 ++-
 1 file changed, 112 insertions(+), 88 deletions(-)

diff --git a/Documentation/bcache.txt b/Documentation/bcache.txt
index a9259b562d5c..c0ce64d75bbf 100644
--- a/Documentation/bcache.txt
+++ b/Documentation/bcache.txt
@@ -1,10 +1,15 @@
+
+A block layer cache (bcache)
+
+
 Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
 nice if you could use them as cache... Hence bcache.
 
 Wiki and git repositories are at:
-  http://bcache.evilpiepirate.org
-  http://evilpiepirate.org/git/linux-bcache.git
-  http://evilpiepirate.org/git/bcache-tools.git
+
+  - http://bcache.evilpiepirate.org
+  - http://evilpiepirate.org/git/linux-bcache.git
+  - http://evilpiepirate.org/git/bcache-tools.git
 
 It's designed around the performance characteristics of SSDs - it only 
allocates
 in erase block sized buckets, and it uses a hybrid btree/log to track cached
@@ -37,17 +42,19 @@ to be flushed.
 
 Getting started:
 You'll need make-bcache from the bcache-tools repository. Both the cache device
-and backing device must be formatted before use.
+and backing device must be formatted before use::
+
   make-bcache -B /dev/sdb
   make-bcache -C /dev/sdc
 
 make-bcache has the ability to format multiple devices at the same time - if
 you format your backing devices and cache device at the same time, you won't
-have to manually attach:
+have to manually attach::
+
   make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
 
 bcache-tools now ships udev rules, and bcache devices are known to the kernel
-immediately.  Without udev, you can manually register devices like this:
+immediately.  Without udev, you can manually register devices like this::
 
   echo /dev/sdb > /sys/fs/bcache/register
   echo /dev/sdc > /sys/fs/bcache/register
@@ -60,16 +67,16 @@ slow devices as bcache backing devices without a cache, and 
you can choose to ad
 a caching device later.
 See 'ATTACHING' section below.
 
-The devices show up as:
+The devices show up as::
 
   /dev/bcache
 
-As well as (with udev):
+As well as (with udev)::
 
   /dev/bcache/by-uuid/
   /dev/bcache/by-label/
 
-To get started:
+To get started::
 
   mkfs.ext4 /dev/bcache0
   mount /dev/bcache0 /mnt
@@ -81,13 +88,13 @@ Cache devices are managed as sets; multiple caches per set 
isn't supported yet
 but will allow for mirroring of metadata and dirty data in the future. Your new
 cache set shows up as /sys/fs/bcache/
 
-ATTACHING
+Attaching
 -
 
 After your cache device and backing device are registered, the backing device
 must be attached to your cache set to enable caching. Attaching a backing
 device to a cache set is done thusly, with the UUID of the cache set in
-/sys/fs/bcache:
+/sys/fs/bcache::
 
   echo  > /sys/block/bcache0/bcache/attach
 
@@ -97,7 +104,7 @@ your bcache devices. If a backing device has data in a cache 
somewhere, the
 important if you have writeback caching turned on.
 
 If you're booting up and your cache device is gone and never coming back, you
-can force run the backing device:
+can force run the backing device::
 
   echo 1 > /sys/block/sdb/bcache/running
 
@@ -110,7 +117,7 @@ but all the cached data will be invalidated. If there was 
dirty data in the
 cache, don't expect the filesystem to be recoverable - you will have massive
 filesystem corruption, though ext4's fsck does work miracles.
 
-ERROR HANDLING
+Error Handling
 --
 
 Bcache tries to transparently handle IO errors to/from the cache device without
@@ -134,25 +141,27 @@ the backing devices to passthrough mode.
read some of the dirty data, though.
 
 
-HOWTO/COOKBOOK
+Howto/cookbook
 --
 
 A) Starting a bcache with a missing caching device
 
 If registering the backing device doesn't help, it's already there, you just 
need
-to force it to run without the cache:
+to force it to run without the cache::
+
host:~# echo /dev/sdb1 > /sys/fs/bcache/register
[  119.844831] bcache: register_bcache() error opening /dev/sdb1: 
device already registered
 
 Next, you try to register your caching device if it's present. However
 if it's absent, or registration fails for some reason, you can still
-start your bcache without its cache, like so:
+start your bcache without its cache, like so::
+
host:/sys/block/sdb/sdb1/bcache# echo 1 > running
 
 Note that this may cause data loss if you were running in writeback mode.
 
 
-B) Bcache does not find its cache
+B) Bcache does not find its cache::

[PATCH 06/31] cgroup-v2.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:

- Comment the internal index;
- Use :Date: and :Author: for authorship;
- Mark titles;
- Mark literal blocks;
- Adjust witespaces;
- Mark notes;
- Use table notation for the existing tables.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/cgroup-v2.txt | 449 +++-
 1 file changed, 234 insertions(+), 215 deletions(-)

diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt
index dc5e2dcdbef4..491dd0200395 100644
--- a/Documentation/cgroup-v2.txt
+++ b/Documentation/cgroup-v2.txt
@@ -1,7 +1,9 @@
-
+
 Control Group v2
+
 
-October, 2015  Tejun Heo 
+:Date: October, 2015
+:Author: Tejun Heo 
 
 This is the authoritative documentation on the design, interface and
 conventions of cgroup v2.  It describes all userland-visible aspects
@@ -9,70 +11,72 @@ of cgroup including core and specific controller behaviors.  
All
 future changes must be reflected in this document.  Documentation for
 v1 is available under Documentation/cgroup-v1/.
 
-CONTENTS
+.. CONTENTS
 
-1. Introduction
-  1-1. Terminology
-  1-2. What is cgroup?
-2. Basic Operations
-  2-1. Mounting
-  2-2. Organizing Processes
-  2-3. [Un]populated Notification
-  2-4. Controlling Controllers
-2-4-1. Enabling and Disabling
-2-4-2. Top-down Constraint
-2-4-3. No Internal Process Constraint
-  2-5. Delegation
-2-5-1. Model of Delegation
-2-5-2. Delegation Containment
-  2-6. Guidelines
-2-6-1. Organize Once and Control
-2-6-2. Avoid Name Collisions
-3. Resource Distribution Models
-  3-1. Weights
-  3-2. Limits
-  3-3. Protections
-  3-4. Allocations
-4. Interface Files
-  4-1. Format
-  4-2. Conventions
-  4-3. Core Interface Files
-5. Controllers
-  5-1. CPU
-5-1-1. CPU Interface Files
-  5-2. Memory
-5-2-1. Memory Interface Files
-5-2-2. Usage Guidelines
-5-2-3. Memory Ownership
-  5-3. IO
-5-3-1. IO Interface Files
-5-3-2. Writeback
-  5-4. PID
-5-4-1. PID Interface Files
-  5-5. RDMA
-5-5-1. RDMA Interface Files
-  5-6. Misc
-5-6-1. perf_event
-6. Namespace
-  6-1. Basics
-  6-2. The Root and Views
-  6-3. Migration and setns(2)
-  6-4. Interaction with Other Namespaces
-P. Information on Kernel Programming
-  P-1. Filesystem Support for Writeback
-D. Deprecated v1 Core Features
-R. Issues with v1 and Rationales for v2
-  R-1. Multiple Hierarchies
-  R-2. Thread Granularity
-  R-3. Competition Between Inner Nodes and Threads
-  R-4. Other Interface Issues
-  R-5. Controller Issues and Remedies
-R-5-1. Memory
+   1. Introduction
+ 1-1. Terminology
+ 1-2. What is cgroup?
+   2. Basic Operations
+ 2-1. Mounting
+ 2-2. Organizing Processes
+ 2-3. [Un]populated Notification
+ 2-4. Controlling Controllers
+   2-4-1. Enabling and Disabling
+   2-4-2. Top-down Constraint
+   2-4-3. No Internal Process Constraint
+ 2-5. Delegation
+   2-5-1. Model of Delegation
+   2-5-2. Delegation Containment
+ 2-6. Guidelines
+   2-6-1. Organize Once and Control
+   2-6-2. Avoid Name Collisions
+   3. Resource Distribution Models
+ 3-1. Weights
+ 3-2. Limits
+ 3-3. Protections
+ 3-4. Allocations
+   4. Interface Files
+ 4-1. Format
+ 4-2. Conventions
+ 4-3. Core Interface Files
+   5. Controllers
+ 5-1. CPU
+   5-1-1. CPU Interface Files
+ 5-2. Memory
+   5-2-1. Memory Interface Files
+   5-2-2. Usage Guidelines
+   5-2-3. Memory Ownership
+ 5-3. IO
+   5-3-1. IO Interface Files
+   5-3-2. Writeback
+ 5-4. PID
+   5-4-1. PID Interface Files
+ 5-5. RDMA
+   5-5-1. RDMA Interface Files
+ 5-6. Misc
+   5-6-1. perf_event
+   6. Namespace
+ 6-1. Basics
+ 6-2. The Root and Views
+ 6-3. Migration and setns(2)
+ 6-4. Interaction with Other Namespaces
+   P. Information on Kernel Programming
+ P-1. Filesystem Support for Writeback
+   D. Deprecated v1 Core Features
+   R. Issues with v1 and Rationales for v2
+ R-1. Multiple Hierarchies
+ R-2. Thread Granularity
+ R-3. Competition Between Inner Nodes and Threads
+ R-4. Other Interface Issues
+ R-5. Controller Issues and Remedies
+   R-5-1. Memory
 
 
-1. Introduction
+Introduction
+
 
-1-1. Terminology
+Terminology
+---
 
 "cgroup" stands for "control group" and is never capitalized.  The
 singular form is used to designate the whole feature and also as a
@@ -80,7 +84,8 @@ qualifier as in "cgroup controllers".  When explicitly 
referring to
 multiple individual control groups, the plural form "cgroups" is used.
 
 
-1-2. What is cgroup?
+What is cgroup?
+---
 
 cgroup is a 

[PATCH 20/31] eisa.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 ReST notation for titles;
- identify literal blocks;
- use :Author: for document authorship;
- use the proper notation for tables;
- adjust whitespaces where needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/eisa.txt | 260 +++--
 1 file changed, 143 insertions(+), 117 deletions(-)

diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt
index a55e4910924e..8e2c6e2b2a19 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.txt
@@ -1,4 +1,7 @@
-EISA bus support (Marc Zyngier )
+EISA bus support
+
+
+:Author: Marc Zyngier 
 
 This document groups random notes about porting EISA drivers to the
 new EISA/sysfs API.
@@ -14,168 +17,189 @@ detection code is generally also used to probe ISA 
cards). Moreover,
 most EISA drivers are among the oldest Linux drivers so, as you can
 imagine, some dust has settled here over the years.
 
-The EISA infrastructure is made up of three parts :
+The EISA infrastructure is made up of three parts:
 
 - The bus code implements most of the generic code. It is shared
-among all the architectures that the EISA code runs on. It
-implements bus probing (detecting EISA cards available on the bus),
-allocates I/O resources, allows fancy naming through sysfs, and
-offers interfaces for driver to register.
+  among all the architectures that the EISA code runs on. It
+  implements bus probing (detecting EISA cards available on the bus),
+  allocates I/O resources, allows fancy naming through sysfs, and
+  offers interfaces for driver to register.
 
 - The bus root driver implements the glue between the bus hardware
-and the generic bus code. It is responsible for discovering the
-device implementing the bus, and setting it up to be latter probed
-by the bus code. This can go from something as simple as reserving
-an I/O region on x86, to the rather more complex, like the hppa
-EISA code. This is the part to implement in order to have EISA
-running on an "new" platform.
+  and the generic bus code. It is responsible for discovering the
+  device implementing the bus, and setting it up to be latter probed
+  by the bus code. This can go from something as simple as reserving
+  an I/O region on x86, to the rather more complex, like the hppa
+  EISA code. This is the part to implement in order to have EISA
+  running on an "new" platform.
 
 - The driver offers the bus a list of devices that it manages, and
-implements the necessary callbacks to probe and release devices
-whenever told to.
+  implements the necessary callbacks to probe and release devices
+  whenever told to.
 
 Every function/structure below lives in , which depends
 heavily on .
 
-** Bus root driver :
+Bus root driver
+===
 
-int eisa_root_register (struct eisa_root_device *root);
+::
+
+   int eisa_root_register (struct eisa_root_device *root);
 
 The eisa_root_register function is used to declare a device as the
 root of an EISA bus. The eisa_root_device structure holds a reference
-to this device, as well as some parameters for probing purposes.
+to this device, as well as some parameters for probing purposes::
 
-struct eisa_root_device {
-   struct device   *dev;/* Pointer to bridge device */
-   struct resource *res;
-   unsigned longbus_base_addr;
-   int  slots;  /* Max slot number */
-   int  force_probe; /* Probe even when no slot 0 */
-   u64  dma_mask; /* from bridge device */
-   int  bus_nr; /* Set by eisa_root_register */
-   struct resource  eisa_root_res; /* ditto */
-};
+   struct eisa_root_device {
+   struct device   *dev;/* Pointer to bridge device */
+   struct resource *res;
+   unsigned longbus_base_addr;
+   int  slots;  /* Max slot number */
+   int  force_probe; /* Probe even when no slot 0 */
+   u64  dma_mask; /* from bridge device */
+   int  bus_nr; /* Set by eisa_root_register */
+   struct resource  eisa_root_res; /* ditto */
+   };
 
-node  : used for eisa_root_register internal purpose
-dev   : pointer to the root device
-res   : root device I/O resource
-bus_base_addr : slot 0 address on this bus
-slots: max slot number to probe
-force_probe   : Probe even when slot 0 is empty (no EISA mainboard)
-dma_mask  : Default DMA mask. Usually the bridge device dma_mask.
-bus_nr   : unique bus id, set by 

[PATCH 28/31] Intel-IOMMU.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 file is almost in the right format. It only needed to
convert a list to bulleted list and to use the right markup
for literal blocks.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/Intel-IOMMU.txt | 36 +++-
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt
index 49585b6e1ea2..11151bd39b2f 100644
--- a/Documentation/Intel-IOMMU.txt
+++ b/Documentation/Intel-IOMMU.txt
@@ -9,11 +9,11 @@ This guide gives a quick cheat sheet for some basic 
understanding.
 
 Some Keywords
 
-DMAR - DMA remapping
-DRHD - DMA Remapping Hardware Unit Definition
-RMRR - Reserved memory Region Reporting Structure
-ZLR  - Zero length reads from PCI devices
-IOVA - IO Virtual address.
+- DMAR - DMA remapping
+- DRHD - DMA Remapping Hardware Unit Definition
+- RMRR - Reserved memory Region Reporting Structure
+- ZLR  - Zero length reads from PCI devices
+- IOVA - IO Virtual address.
 
 Basic stuff
 ---
@@ -33,7 +33,7 @@ devices that need to access these regions. OS is expected to 
setup
 unity mappings for these regions for these devices to access these regions.
 
 How is IOVA generated?
--
+--
 
 Well behaved drivers call pci_map_*() calls before sending command to device
 that needs to perform DMA. Once DMA is completed and mapping is no longer
@@ -82,14 +82,14 @@ in ACPI.
 ACPI: DMAR (v001 A M I  OEMDMAR  0x0001 MSFT 0x0097) @ 
0x7f5b5ef0
 
 When DMAR is being processed and initialized by ACPI, prints DMAR locations
-and any RMRR's processed.
+and any RMRR's processed::
 
-ACPI DMAR:Host address width 36
-ACPI DMAR:DRHD (flags: 0x)base: 0xfed9
-ACPI DMAR:DRHD (flags: 0x)base: 0xfed91000
-ACPI DMAR:DRHD (flags: 0x0001)base: 0xfed93000
-ACPI DMAR:RMRR base: 0x000ed000 end: 0x000e
-ACPI DMAR:RMRR base: 0x7f60 end: 0x7fff
+   ACPI DMAR:Host address width 36
+   ACPI DMAR:DRHD (flags: 0x)base: 0xfed9
+   ACPI DMAR:DRHD (flags: 0x)base: 0xfed91000
+   ACPI DMAR:DRHD (flags: 0x0001)base: 0xfed93000
+   ACPI DMAR:RMRR base: 0x000ed000 end: 0x000e
+   ACPI DMAR:RMRR base: 0x7f60 end: 0x7fff
 
 When DMAR is enabled for use, you will notice..
 
@@ -98,10 +98,12 @@ PCI-DMA: Using DMAR IOMMU
 Fault reporting
 ---
 
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
+::
+
+   DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
+   DMAR:[fault reason 05] PTE Write access is not set
+   DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
+   DMAR:[fault reason 05] PTE Write access is not set
 
 TBD
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 25/31] hw_random.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 proper markups for titles;
- adjust section identation;
- use proper markup for notes and fix it to properly show the
  numbered list.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/hw_random.txt | 158 
 1 file changed, 86 insertions(+), 72 deletions(-)

diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.txt
index fce1634907d0..865e997d9d3b 100644
--- a/Documentation/hw_random.txt
+++ b/Documentation/hw_random.txt
@@ -1,90 +1,104 @@
-Introduction:
-
-   The hw_random framework is software that makes use of a
-   special hardware feature on your CPU or motherboard,
-   a Random Number Generator (RNG).  The software has two parts:
-   a core providing the /dev/hwrng character device and its
-   sysfs support, plus a hardware-specific driver that plugs
-   into that core.
-
-   To make the most effective use of these mechanisms, you
-   should download the support software as well.  Download the
-   latest version of the "rng-tools" package from the
-   hw_random driver's official Web site:
-
-   http://sourceforge.net/projects/gkernel/
-
-   Those tools use /dev/hwrng to fill the kernel entropy pool,
-   which is used internally and exported by the /dev/urandom and
-   /dev/random special files.
-
-Theory of operation:
-
-   CHARACTER DEVICE.  Using the standard open()
-   and read() system calls, you can read random data from
-   the hardware RNG device.  This data is NOT CHECKED by any
-   fitness tests, and could potentially be bogus (if the
-   hardware is faulty or has been tampered with).  Data is only
-   output if the hardware "has-data" flag is set, but nevertheless
-   a security-conscious person would run fitness tests on the
-   data before assuming it is truly random.
-
-   The rng-tools package uses such tests in "rngd", and lets you
-   run them by hand with a "rngtest" utility.
-
-   /dev/hwrng is char device major 10, minor 183.
-
-   CLASS DEVICE.  There is a /sys/class/misc/hw_random node with
-   two unique attributes, "rng_available" and "rng_current".  The
-   "rng_available" attribute lists the hardware-specific drivers
-   available, while "rng_current" lists the one which is currently
-   connected to /dev/hwrng.  If your system has more than one
-   RNG available, you may change the one used by writing a name from
-   the list in "rng_available" into "rng_current".
+Linux support for random number generator in i8xx chipsets
+==
+
+Introduction
+
+
+The hw_random framework is software that makes use of a
+special hardware feature on your CPU or motherboard,
+a Random Number Generator (RNG).  The software has two parts:
+a core providing the /dev/hwrng character device and its
+sysfs support, plus a hardware-specific driver that plugs
+into that core.
+
+To make the most effective use of these mechanisms, you
+should download the support software as well.  Download the
+latest version of the "rng-tools" package from the
+hw_random driver's official Web site:
+
+   http://sourceforge.net/projects/gkernel/
+
+Those tools use /dev/hwrng to fill the kernel entropy pool,
+which is used internally and exported by the /dev/urandom and
+/dev/random special files.
+
+Theory of operation
+===
+
+CHARACTER DEVICE.  Using the standard open()
+and read() system calls, you can read random data from
+the hardware RNG device.  This data is NOT CHECKED by any
+fitness tests, and could potentially be bogus (if the
+hardware is faulty or has been tampered with).  Data is only
+output if the hardware "has-data" flag is set, but nevertheless
+a security-conscious person would run fitness tests on the
+data before assuming it is truly random.
+
+The rng-tools package uses such tests in "rngd", and lets you
+run them by hand with a "rngtest" utility.
+
+/dev/hwrng is char device major 10, minor 183.
+
+CLASS DEVICE.  There is a /sys/class/misc/hw_random node with
+two unique attributes, "rng_available" and "rng_current".  The
+"rng_available" attribute lists the hardware-specific drivers
+available, while "rng_current" lists the one which is currently
+connected to /dev/hwrng.  If your system has more than one
+RNG available, you may change the one used by writing a name from
+the list in "rng_available" into "rng_current".
 
 ==
 
-   Hardware driver for Intel/AMD/VIA Random Number Generators (RNG)
-   Copyright 2000,2001 Jeff Garzik 
-   Copyright 2000,2001 Philipp Rumpf 

[PATCH 31/31] iostats.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 main title level;
- mark literal blocks as such;
- Add blank lines to avoid Sphinx errors.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/iostats.txt | 40 +++-
 1 file changed, 27 insertions(+), 13 deletions(-)

diff --git a/Documentation/iostats.txt b/Documentation/iostats.txt
index 65f694f2d1c9..456a5b5e0c53 100644
--- a/Documentation/iostats.txt
+++ b/Documentation/iostats.txt
@@ -1,5 +1,6 @@
+=
 I/O statistics fields

+=
 
 Since 2.4.20 (and some versions before, with patches), and 2.5.45,
 more extensive disk statistics have been introduced to help measure disk
@@ -16,20 +17,20 @@ is mounted on /sys, although of course it may be mounted 
anywhere.
 Both /proc/diskstats and sysfs use the same source for the information
 and so should not differ.
 
-Here are examples of these different formats:
+Here are examples of these different formats::
 
-2.4:
-   3 0   39082680 hda 446216 784926 9550688 4382310 424847 312726 5922052 
19310380 0 3376340 23705160
-   3 19221278 hda1 35486 0 35496 38030 0 0 0 0 0 38030 38030
+   2.4:
+  3 0   39082680 hda 446216 784926 9550688 4382310 424847 312726 
5922052 19310380 0 3376340 23705160
+  3 19221278 hda1 35486 0 35496 38030 0 0 0 0 0 38030 38030
 
 
-2.6 sysfs:
-   446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 
23705160
-   35486380303803038030
+   2.6 sysfs:
+  446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 
23705160
+  35486380303803038030
 
-2.6 diskstats:
-   30   hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 
3376340 23705160
-   31   hda1 35486 38030 38030 38030
+   2.6 diskstats:
+  30   hda 446216 784926 9550688 4382310 424847 312726 5922052 
19310380 0 3376340 23705160
+  31   hda1 35486 38030 38030 38030
 
 On 2.4 you might execute "grep 'hda ' /proc/partitions". On 2.6, you have
 a choice of "cat /sys/block/hda/stat" or "grep 'hda ' /proc/diskstats".
@@ -59,30 +60,40 @@ system-wide stats you'll have to find all the devices and 
sum them all up.
 
 Field  1 -- # of reads completed
 This is the total number of reads completed successfully.
+
 Field  2 -- # of reads merged, field 6 -- # of writes merged
 Reads and writes which are adjacent to each other may be merged for
 efficiency.  Thus two 4K reads may become one 8K read before it is
 ultimately handed to the disk, and so it will be counted (and queued)
 as only one I/O.  This field lets you know how often this was done.
+
 Field  3 -- # of sectors read
 This is the total number of sectors read successfully.
+
 Field  4 -- # of milliseconds spent reading
 This is the total number of milliseconds spent by all reads (as
 measured from __make_request() to end_that_request_last()).
+
 Field  5 -- # of writes completed
 This is the total number of writes completed successfully.
+
 Field  6 -- # of writes merged
 See the description of field 2.
+
 Field  7 -- # of sectors written
 This is the total number of sectors written successfully.
+
 Field  8 -- # of milliseconds spent writing
 This is the total number of milliseconds spent by all writes (as
 measured from __make_request() to end_that_request_last()).
+
 Field  9 -- # of I/Os currently in progress
 The only field that should go to zero. Incremented as requests are
 given to appropriate struct request_queue and decremented as they finish.
+
 Field 10 -- # of milliseconds spent doing I/Os
 This field increases so long as field 9 is nonzero.
+
 Field 11 -- weighted # of milliseconds spent doing I/Os
 This field is incremented at each I/O start, I/O completion, I/O
 merge, or read of these stats by the number of I/Os in progress
@@ -117,11 +128,14 @@ for partitions on 2.6 machines.  This is reflected in the 
examples above.
 
 Field  1 -- # of reads issued
 This is the total number of reads issued to this partition.
+
 Field  2 -- # of sectors read
 This is the total number of sectors requested to be read from this
 partition.
+
 Field  3 -- # of writes issued
 This is the total number of writes issued to this partition.
+
 Field  4 -- # of sectors written
 This is the total number of sectors requested to be written to
 this partition.
@@ -151,9 +165,9 @@ Additional notes
 
 In 2.6, sysfs is not mounted by default.  If your distribution of
 Linux hasn't added it already, here's the line you'll want to add to
-your /etc/fstab:
+your /etc/fstab::
 
-none /sys sysfs defaults 0 0
+   none /sys sysfs defaults 0 0
 
 
 In 2.6, all disk statistics were removed from 

[PATCH 30/31] io_ordering.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;
- mark literal-blocks as such.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/io_ordering.txt | 61 +++
 1 file changed, 32 insertions(+), 29 deletions(-)

diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.txt
index 9faae6f26d32..01d2875b5076 100644
--- a/Documentation/io_ordering.txt
+++ b/Documentation/io_ordering.txt
@@ -1,3 +1,6 @@
+Ordering I/O writes to memory-mapped addresses
+==
+
 On some platforms, so-called memory-mapped I/O is weakly ordered.  On such
 platforms, driver writers are responsible for ensuring that I/O writes to
 memory-mapped addresses on their device arrive in the order intended.  This is
@@ -8,39 +11,39 @@ critical section of code protected by spinlocks.  This would 
ensure that
 subsequent writes to I/O space arrived only after all prior writes (much like a
 memory barrier op, mb(), only with respect to I/O).
 
-A more concrete example from a hypothetical device driver:
+A more concrete example from a hypothetical device driver::
 
-...
-CPU A:  spin_lock_irqsave(_lock, flags)
-CPU A:  val = readl(my_status);
-CPU A:  ...
-CPU A:  writel(newval, ring_ptr);
-CPU A:  spin_unlock_irqrestore(_lock, flags)
-...
-CPU B:  spin_lock_irqsave(_lock, flags)
-CPU B:  val = readl(my_status);
-CPU B:  ...
-CPU B:  writel(newval2, ring_ptr);
-CPU B:  spin_unlock_irqrestore(_lock, flags)
-...
+   ...
+   CPU A:  spin_lock_irqsave(_lock, flags)
+   CPU A:  val = readl(my_status);
+   CPU A:  ...
+   CPU A:  writel(newval, ring_ptr);
+   CPU A:  spin_unlock_irqrestore(_lock, flags)
+   ...
+   CPU B:  spin_lock_irqsave(_lock, flags)
+   CPU B:  val = readl(my_status);
+   CPU B:  ...
+   CPU B:  writel(newval2, ring_ptr);
+   CPU B:  spin_unlock_irqrestore(_lock, flags)
+   ...
 
 In the case above, the device may receive newval2 before it receives newval,
-which could cause problems.  Fixing it is easy enough though:
+which could cause problems.  Fixing it is easy enough though::
 
-...
-CPU A:  spin_lock_irqsave(_lock, flags)
-CPU A:  val = readl(my_status);
-CPU A:  ...
-CPU A:  writel(newval, ring_ptr);
-CPU A:  (void)readl(safe_register); /* maybe a config register? */
-CPU A:  spin_unlock_irqrestore(_lock, flags)
-...
-CPU B:  spin_lock_irqsave(_lock, flags)
-CPU B:  val = readl(my_status);
-CPU B:  ...
-CPU B:  writel(newval2, ring_ptr);
-CPU B:  (void)readl(safe_register); /* maybe a config register? */
-CPU B:  spin_unlock_irqrestore(_lock, flags)
+   ...
+   CPU A:  spin_lock_irqsave(_lock, flags)
+   CPU A:  val = readl(my_status);
+   CPU A:  ...
+   CPU A:  writel(newval, ring_ptr);
+   CPU A:  (void)readl(safe_register); /* maybe a config register? */
+   CPU A:  spin_unlock_irqrestore(_lock, flags)
+   ...
+   CPU B:  spin_lock_irqsave(_lock, flags)
+   CPU B:  val = readl(my_status);
+   CPU B:  ...
+   CPU B:  writel(newval2, ring_ptr);
+   CPU B:  (void)readl(safe_register); /* maybe a config register? */
+   CPU B:  spin_unlock_irqrestore(_lock, flags)
 
 Here, the reads from safe_register will cause the I/O chipset to flush any
 pending writes before actually posting the read to the chipset, preventing
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 01/30] iostats.txt: update it to cover recent Kernels

[Mauro Carvalho Chehab]

Everything there that it is said for 2.6 also applies on
current 4.x Kernels. So, update the information there.

While here, use ``foo`` for literals.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/iostats.txt | 44 ++--
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/iostats.txt b/Documentation/iostats.txt
index 456a5b5e0c53..04d394a2e06c 100644
--- a/Documentation/iostats.txt
+++ b/Documentation/iostats.txt
@@ -4,17 +4,17 @@ I/O statistics fields
 
 Since 2.4.20 (and some versions before, with patches), and 2.5.45,
 more extensive disk statistics have been introduced to help measure disk
-activity. Tools such as sar and iostat typically interpret these and do
+activity. Tools such as ``sar`` and ``iostat`` typically interpret these and do
 the work for you, but in case you are interested in creating your own
 tools, the fields are explained here.
 
 In 2.4 now, the information is found as additional fields in
-/proc/partitions.  In 2.6, the same information is found in two
-places: one is in the file /proc/diskstats, and the other is within
+``/proc/partitions``.  In 2.6 and upper, the same information is found in two
+places: one is in the file ``/proc/diskstats``, and the other is within
 the sysfs file system, which must be mounted in order to obtain
 the information. Throughout this document we'll assume that sysfs
-is mounted on /sys, although of course it may be mounted anywhere.
-Both /proc/diskstats and sysfs use the same source for the information
+is mounted on ``/sys``, although of course it may be mounted anywhere.
+Both ``/proc/diskstats`` and sysfs use the same source for the information
 and so should not differ.
 
 Here are examples of these different formats::
@@ -23,28 +23,28 @@ Here are examples of these different formats::
   3 0   39082680 hda 446216 784926 9550688 4382310 424847 312726 
5922052 19310380 0 3376340 23705160
   3 19221278 hda1 35486 0 35496 38030 0 0 0 0 0 38030 38030
 
-
-   2.6 sysfs:
+   2.6+ sysfs:
   446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 
23705160
   35486380303803038030
 
-   2.6 diskstats:
+   2.6+ diskstats:
   30   hda 446216 784926 9550688 4382310 424847 312726 5922052 
19310380 0 3376340 23705160
   31   hda1 35486 38030 38030 38030
 
-On 2.4 you might execute "grep 'hda ' /proc/partitions". On 2.6, you have
-a choice of "cat /sys/block/hda/stat" or "grep 'hda ' /proc/diskstats".
+On 2.4 you might execute ``grep 'hda ' /proc/partitions``. On 2.6+, you have
+a choice of ``cat /sys/block/hda/stat`` or ``grep 'hda ' /proc/diskstats``.
+
 The advantage of one over the other is that the sysfs choice works well
-if you are watching a known, small set of disks.  /proc/diskstats may
+if you are watching a known, small set of disks.  ``/proc/diskstats`` may
 be a better choice if you are watching a large number of disks because
 you'll avoid the overhead of 50, 100, or 500 or more opens/closes with
 each snapshot of your disk statistics.
 
 In 2.4, the statistics fields are those after the device name. In
 the above example, the first field of statistics would be 446216.
-By contrast, in 2.6 if you look at /sys/block/hda/stat, you'll
+By contrast, in 2.6+ if you look at ``/sys/block/hda/stat``, you'll
 find just the eleven fields, beginning with 446216.  If you look at
-/proc/diskstats, the eleven fields will be preceded by the major and
+``/proc/diskstats``, the eleven fields will be preceded by the major and
 minor device numbers, and device name.  Each of these formats provides
 eleven fields of statistics, each meaning exactly the same things.
 All fields except field 9 are cumulative since boot.  Field 9 should
@@ -108,7 +108,7 @@ introduced when changes collide, so (for instance) adding 
up all the
 read I/Os issued per partition should equal those made to the disks ...
 but due to the lack of locking it may only be very close.
 
-In 2.6, there are counters for each CPU, which make the lack of locking
+In 2.6+, there are counters for each CPU, which make the lack of locking
 almost a non-issue.  When the statistics are read, the per-CPU counters
 are summed (possibly overflowing the unsigned long variable they are
 summed to) and the result given to the user.  There is no convenient
@@ -117,14 +117,14 @@ user interface for accessing the per-CPU counters 
themselves.
 Disks vs Partitions
 ---
 
-There were significant changes between 2.4 and 2.6 in the I/O subsystem.
+There were significant changes between 2.4 and 2.6+ in the I/O subsystem.
 As a result, some statistic information disappeared. The translation from
 a disk address relative to a partition to the disk address relative to
 the host disk happens much earlier.  All merges and timings now happen
 at the disk level rather than at both the disk and partition level as
-in 2.4.  Consequently, 

[PATCH 02/30] IPMI.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:

- fix document type;
- add missing markups for subitems;
- mark literal blocks;
- add whitespaces and blank lines where needed;
- use bulleted list markups where neded.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/IPMI.txt | 76 +-
 1 file changed, 44 insertions(+), 32 deletions(-)

diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt
index 6962cab997ef..aa77a25a0940 100644
--- a/Documentation/IPMI.txt
+++ b/Documentation/IPMI.txt
@@ -1,9 +1,8 @@
+=
+The Linux IPMI Driver
+=
 
-  The Linux IPMI Driver
- -
- Corey Minyard
- 
-   
+:Author: Corey Minyard  / 
 
 The Intelligent Platform Management Interface, or IPMI, is a
 standard for controlling intelligent devices that monitor a system.
@@ -141,7 +140,7 @@ Addressing
 --
 
 The IPMI addressing works much like IP addresses, you have an overlay
-to handle the different address types.  The overlay is:
+to handle the different address types.  The overlay is::
 
   struct ipmi_addr
   {
@@ -153,7 +152,7 @@ to handle the different address types.  The overlay is:
 The addr_type determines what the address really is.  The driver
 currently understands two different types of addresses.
 
-"System Interface" addresses are defined as:
+"System Interface" addresses are defined as::
 
   struct ipmi_system_interface_addr
   {
@@ -166,7 +165,7 @@ straight to the BMC on the current card.  The channel must 
be
 IPMI_BMC_CHANNEL.
 
 Messages that are destined to go out on the IPMB bus use the
-IPMI_IPMB_ADDR_TYPE address type.  The format is
+IPMI_IPMB_ADDR_TYPE address type.  The format is::
 
   struct ipmi_ipmb_addr
   {
@@ -184,16 +183,16 @@ spec.
 Messages
 
 
-Messages are defined as:
+Messages are defined as::
 
-struct ipmi_msg
-{
+  struct ipmi_msg
+  {
unsigned char netfn;
unsigned char lun;
unsigned char cmd;
unsigned char *data;
int   data_len;
-};
+  };
 
 The driver takes care of adding/stripping the header information.  The
 data portion is just the data to be send (do NOT put addressing info
@@ -208,7 +207,7 @@ block of data, even when receiving messages.  Otherwise the 
driver
 will have no place to put the message.
 
 Messages coming up from the message handler in kernelland will come in
-as:
+as::
 
   struct ipmi_recv_msg
   {
@@ -246,6 +245,7 @@ and the user should not have to care what type of SMI is 
below them.
 
 
 Watching For Interfaces
+^^^
 
 When your code comes up, the IPMI driver may or may not have detected
 if IPMI devices exist.  So you might have to defer your setup until
@@ -256,6 +256,7 @@ and tell you when they come and go.
 
 
 Creating the User
+^
 
 To use the message handler, you must first create a user using
 ipmi_create_user.  The interface number specifies which SMI you want
@@ -272,6 +273,7 @@ closing the device automatically destroys the user.
 
 
 Messaging
+^
 
 To send a message from kernel-land, the ipmi_request_settime() call does
 pretty much all message handling.  Most of the parameter are
@@ -321,6 +323,7 @@ though, since it is tricky to manage your own buffers.
 
 
 Events and Incoming Commands
+
 
 The driver takes care of polling for IPMI events and receiving
 commands (commands are messages that are not responses, they are
@@ -367,7 +370,7 @@ in the system.  It discovers interfaces through a host of 
different
 methods, depending on the system.
 
 You can specify up to four interfaces on the module load line and
-control some module parameters:
+control some module parameters::
 
   modprobe ipmi_si.o type=,
ports=,... addrs=,...
@@ -437,7 +440,7 @@ default is one.  Setting to 0 is useful with the hotmod, 
but is
 obviously only useful for modules.
 
 When compiled into the kernel, the parameters can be specified on the
-kernel command line as:
+kernel command line as::
 
   ipmi_si.type=,...
ipmi_si.ports=,... ipmi_si.addrs=,...
@@ -474,16 +477,22 @@ The driver supports a hot add and remove of interfaces.  
This way,
 interfaces can be added or removed after the kernel is up and running.
 This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a
 write-only parameter.  You write a string to this interface.  The string
-has the format:
+has the format::
+
[:op2[:op3...]]
-The "op"s are:
+
+The "op"s are::
+
add|remove,kcs|bt|smic,mem|i/o,[,[,[,...]]]
-You can specify more than one interface 

[PATCH 10/30] kobject.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 markups for titles;
- mark literal blocks as such;
- add needed whitespace/blank lines;
- use :Author: and :Last updated: for authorship.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kobject.txt | 69 ---
 1 file changed, 42 insertions(+), 27 deletions(-)

diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index 1be59a3a521c..fc9485d79061 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -1,13 +1,13 @@
+=
 Everything you never wanted to know about kobjects, ksets, and ktypes
+=
 
-Greg Kroah-Hartman 
+:Author: Greg Kroah-Hartman 
+:Last updated: December 19, 2007
 
 Based on an original article by Jon Corbet for lwn.net written October 1,
 2003 and located at http://lwn.net/Articles/51437/
 
-Last updated December 19, 2007
-
-
 Part of the difficulty in understanding the driver model - and the kobject
 abstraction upon which it is built - is that there is no obvious starting
 place. Dealing with kobjects requires understanding a few different types,
@@ -47,6 +47,7 @@ approach will be taken, so we'll go back to kobjects.
 
 
 Embedding kobjects
+==
 
 It is rare for kernel code to create a standalone kobject, with one major
 exception explained below.  Instead, kobjects are used to control access to
@@ -65,7 +66,7 @@ their own, but are invariably found embedded in the larger 
objects of
 interest.)
 
 So, for example, the UIO code in drivers/uio/uio.c has a structure that
-defines the memory region associated with a uio device:
+defines the memory region associated with a uio device::
 
 struct uio_map {
struct kobject kobj;
@@ -77,7 +78,7 @@ just a matter of using the kobj member.  Code that works with 
kobjects will
 often have the opposite problem, however: given a struct kobject pointer,
 what is the pointer to the containing structure?  You must avoid tricks
 (such as assuming that the kobject is at the beginning of the structure)
-and, instead, use the container_of() macro, found in :
+and, instead, use the container_of() macro, found in ::
 
 container_of(pointer, type, member)
 
@@ -90,13 +91,13 @@ where:
 The return value from container_of() is a pointer to the corresponding
 container type. So, for example, a pointer "kp" to a struct kobject
 embedded *within* a struct uio_map could be converted to a pointer to the
-*containing* uio_map structure with:
+*containing* uio_map structure with::
 
 struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
 
 For convenience, programmers often define a simple macro for "back-casting"
 kobject pointers to the containing type.  Exactly this happens in the
-earlier drivers/uio/uio.c, as you can see here:
+earlier drivers/uio/uio.c, as you can see here::
 
 struct uio_map {
 struct kobject kobj;
@@ -106,23 +107,25 @@ earlier drivers/uio/uio.c, as you can see here:
 #define to_map(map) container_of(map, struct uio_map, kobj)
 
 where the macro argument "map" is a pointer to the struct kobject in
-question.  That macro is subsequently invoked with:
+question.  That macro is subsequently invoked with::
 
 struct uio_map *map = to_map(kobj);
 
 
 Initialization of kobjects
+==
 
 Code which creates a kobject must, of course, initialize that object. Some
-of the internal fields are setup with a (mandatory) call to kobject_init():
+of the internal fields are setup with a (mandatory) call to kobject_init()::
 
 void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
 
 The ktype is required for a kobject to be created properly, as every kobject
 must have an associated kobj_type.  After calling kobject_init(), to
-register the kobject with sysfs, the function kobject_add() must be called:
+register the kobject with sysfs, the function kobject_add() must be called::
 
-int kobject_add(struct kobject *kobj, struct kobject *parent, const char 
*fmt, ...);
+int kobject_add(struct kobject *kobj, struct kobject *parent,
+   const char *fmt, ...);
 
 This sets up the parent of the kobject and the name for the kobject
 properly.  If the kobject is to be associated with a specific kset,
@@ -133,7 +136,7 @@ kset itself.
 
 As the name of the kobject is set when it is added to the kernel, the name
 of the kobject should never be manipulated directly.  If you must change
-the name of the kobject, call kobject_rename():
+the name of the kobject, call kobject_rename()::
 
 int kobject_rename(struct kobject *kobj, const char 

[PATCH 13/30] kselftest.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 the level of the document title;
- use literal blocks where needed;
- add whitespaces to fix one literal block.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kselftest.txt | 37 +
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt
index 5bd590335839..98be003ce4eb 100644
--- a/Documentation/kselftest.txt
+++ b/Documentation/kselftest.txt
@@ -1,4 +1,6 @@
+==
 Linux Kernel Selftests
+==
 
 The kernel contains a set of "self tests" under the tools/testing/selftests/
 directory. These are intended to be small tests to exercise individual code
@@ -15,14 +17,17 @@ hotplug test is run on 2% of hotplug capable memory instead 
of 10%.
 Running the selftests (hotplug tests are run in limited mode)
 =
 
-To build the tests:
+To build the tests::
+
   $ make -C tools/testing/selftests
 
 
-To run the tests:
+To run the tests::
+
   $ make -C tools/testing/selftests run_tests
 
-To build and run the tests with a single command, use:
+To build and run the tests with a single command, use::
+
   $ make kselftest
 
 - note that some tests will require root privileges.
@@ -33,10 +38,12 @@ Running a subset of selftests
 You can use the "TARGETS" variable on the make command line to specify
 single test to run, or a list of tests to run.
 
-To run only tests targeted for a single subsystem:
+To run only tests targeted for a single subsystem::
+
   $  make -C tools/testing/selftests TARGETS=ptrace run_tests
 
-You can specify multiple tests to build and run:
+You can specify multiple tests to build and run::
+
   $  make TARGETS="size timers" kselftest
 
 See the top-level tools/testing/selftests/Makefile for the list of all
@@ -46,10 +53,12 @@ possible targets.
 Running the full range hotplug selftests
 
 
-To build the hotplug tests:
+To build the hotplug tests::
+
   $ make -C tools/testing/selftests hotplug
 
-To run the hotplug tests:
+To run the hotplug tests::
+
   $ make -C tools/testing/selftests run_hotplug
 
 - note that some tests will require root privileges.
@@ -62,11 +71,13 @@ You can use kselftest_install.sh tool installs selftests in 
default
 location which is tools/testing/selftests/kselftest or a user specified
 location.
 
-To install selftests in default location:
+To install selftests in default location::
+
$ cd tools/testing/selftests
$ ./kselftest_install.sh
 
-To install selftests in a user specified location:
+To install selftests in a user specified location::
+
$ cd tools/testing/selftests
$ ./kselftest_install.sh install_dir
 
@@ -77,10 +88,10 @@ Kselftest install as well as the Kselftest tarball provide 
a script
 named "run_kselftest.sh" to run the tests.
 
 You can simply do the following to run the installed Kselftests. Please
-note some tests will require root privileges.
+note some tests will require root privileges::
 
-cd kselftest
-./run_kselftest.sh
+   $ cd kselftest
+   $ ./run_kselftest.sh
 
 Contributing new tests
 ==
@@ -101,8 +112,10 @@ Contributing new tests(details)
 
  * Use TEST_GEN_XXX if such binaries or files are generated during
compiling.
+
TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by
default.
+
TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
executable which is not tested by default.
TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 14/30] ldm.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:

- Reformat its title;
- Use :Author: and :Last Updated: for authorship
- Use note markup;
- Reformat table to match ReST standard;
- Use bulleted lists where needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ldm.txt | 54 +++
 1 file changed, 33 insertions(+), 21 deletions(-)

diff --git a/Documentation/ldm.txt b/Documentation/ldm.txt
index 4f80edd14d0a..12c571368e73 100644
--- a/Documentation/ldm.txt
+++ b/Documentation/ldm.txt
@@ -1,9 +1,9 @@
+==
+LDM - Logical Disk Manager (Dynamic Disks)
+==
 
-LDM - Logical Disk Manager (Dynamic Disks)
---
-
-Originally Written by FlatCap - Richard Russon .
-Last Updated by Anton Altaparmakov on 30 March 2007 for Windows Vista.
+:Author: Originally Written by FlatCap - Richard Russon .
+:Last Updated: Anton Altaparmakov on 30 March 2007 for Windows Vista.
 
 Overview
 
@@ -37,24 +37,36 @@ Example
 ---
 
 Below we have a 50MiB disk, divided into seven partitions.
-N.B.  The missing 1MiB at the end of the disk is where the LDM database is
-  stored.
 
-  Device | Offset Bytes  Sectors  MiB | Size   Bytes  Sectors  MiB
-  ---++---
-  hda|000 | 52428800   102400   50
-  hda1   | 51380224   100352   49 |  1048576 20481
-  hda2   |16384   320 |  6979584136326
-  hda3   |  6995968136646 | 1048576020480   10
-  hda4   | 1748172834144   16 |  4194304 81924
-  hda5   | 2167603242336   20 |  5242880102405
-  hda6   | 2691891252576   25 | 1048576020480   10
-  hda7   | 3740467273056   35 | 1395916827264   13
+.. note::
+
+   The missing 1MiB at the end of the disk is where the LDM database is
+   stored.
+
++---++--+-+-++--+-++
+|Device || Offset Bytes | Sectors | MiB || Size   Bytes | Sectors | MiB|
++===++==+=+=++==+=++
+|hda||0 |   0 |   0 || 52428800 |  102400 |  50|
++---++--+-+-++--+-++
+|hda1   || 51380224 |  100352 |  49 ||  1048576 |2048 |   1|
++---++--+-+-++--+-++
+|hda2   ||16384 |  32 |   0 ||  6979584 |   13632 |   6|
++---++--+-+-++--+-++
+|hda3   ||  6995968 |   13664 |   6 || 10485760 |   20480 |  10|
++---++--+-+-++--+-++
+|hda4   || 17481728 |   34144 |  16 ||  4194304 |8192 |   4|
++---++--+-+-++--+-++
+|hda5   || 21676032 |   42336 |  20 ||  5242880 |   10240 |   5|
++---++--+-+-++--+-++
+|hda6   || 26918912 |   52576 |  25 || 10485760 |   20480 |  10|
++---++--+-+-++--+-++
+|hda7   || 37404672 |   73056 |  35 || 13959168 |   27264 |  13|
++---++--+-+-++--+-++
 
 The LDM Database may not store the partitions in the order that they appear on
 disk, but the driver will sort them.
 
-When Linux boots, you will see something like:
+When Linux boots, you will see something like::
 
   hda: 102400 sectors w/32KiB Cache, CHS=50/64/32
   hda: [LDM] hda1 hda2 hda3 hda4 hda5 hda6 hda7
@@ -65,13 +77,13 @@ Compiling LDM Support
 
 To enable LDM, choose the following two options: 
 
-  "Advanced partition selection" CONFIG_PARTITION_ADVANCED
-  "Windows Logical Disk Manager (Dynamic Disk) support" CONFIG_LDM_PARTITION
+  - "Advanced partition selection" CONFIG_PARTITION_ADVANCED
+  - "Windows Logical Disk Manager (Dynamic Disk) support" CONFIG_LDM_PARTITION
 
 If you believe the driver isn't working as it should, you can enable the extra
 debugging code.  This will produce a LOT of output.  The option is:
 
-  "Windows LDM extra logging" CONFIG_LDM_DEBUG
+  - "Windows LDM extra logging" CONFIG_LDM_DEBUG
 
 N.B. The partition code cannot be compiled as a module.
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 09/30] kernel-per-CPU-kthreads.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 title markups;
- use "-" for bulletted lists;
- Split Name/Purpose on two lines, in order to make visually
  easier to read (in text format), and to bold the title
  (on ReST output)
- Add blank lines to split bulleted lists;
- use sub-titles for the several kthread softirq types;
- mark one literal var with asterisk as such, in order to
  avoid an error warning on Sphinx.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kernel-per-CPU-kthreads.txt | 156 +++---
 1 file changed, 121 insertions(+), 35 deletions(-)

diff --git a/Documentation/kernel-per-CPU-kthreads.txt 
b/Documentation/kernel-per-CPU-kthreads.txt
index df31e30b6a02..5a09a4a99ecc 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.txt
@@ -1,27 +1,29 @@
-REDUCING OS JITTER DUE TO PER-CPU KTHREADS
+==
+Reducing OS jitter due to per-cpu kthreads
+==
 
 This document lists per-CPU kthreads in the Linux kernel and presents
 options to control their OS jitter.  Note that non-per-CPU kthreads are
 not listed here.  To reduce OS jitter from non-per-CPU kthreads, bind
 them to a "housekeeping" CPU dedicated to such work.
 
+References
+==
 
-REFERENCES
+-  Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
 
-o  Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
+-  Documentation/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
 
-o  Documentation/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
-
-o  man taskset:  Using the taskset command to bind tasks to sets
+-  man taskset:  Using the taskset command to bind tasks to sets
of CPUs.
 
-o  man sched_setaffinity:  Using the sched_setaffinity() system
+-  man sched_setaffinity:  Using the sched_setaffinity() system
call to bind tasks to sets of CPUs.
 
-o  /sys/devices/system/cpu/cpuN/online:  Control CPU N's hotplug state,
+-  /sys/devices/system/cpu/cpuN/online:  Control CPU N's hotplug state,
writing "0" to offline and "1" to online.
 
-o  In order to locate kernel-generated OS jitter on CPU N:
+-  In order to locate kernel-generated OS jitter on CPU N:
 
cd /sys/kernel/debug/tracing
echo 1 > max_graph_depth # Increase the "1" for more detail
@@ -29,12 +31,17 @@ o   In order to locate kernel-generated OS jitter on CPU N:
# run workload
cat per_cpu/cpuN/trace
 
+kthreads
+
 
-KTHREADS
+Name:
+  ehca_comp/%u
+
+Purpose:
+  Periodically process Infiniband-related work.
 
-Name: ehca_comp/%u
-Purpose: Periodically process Infiniband-related work.
 To reduce its OS jitter, do any of the following:
+
 1. Don't use eHCA Infiniband hardware, instead choosing hardware
that does not require per-CPU kthreads.  This will prevent these
kthreads from being created in the first place.  (This will
@@ -46,26 +53,45 @@ To reduce its OS jitter, do any of the following:
provisioned only on selected CPUs.
 
 
-Name: irq/%d-%s
-Purpose: Handle threaded interrupts.
+Name:
+  irq/%d-%s
+
+Purpose:
+  Handle threaded interrupts.
+
 To reduce its OS jitter, do the following:
+
 1. Use irq affinity to force the irq threads to execute on
some other CPU.
 
-Name: kcmtpd_ctr_%d
-Purpose: Handle Bluetooth work.
+Name:
+  kcmtpd_ctr_%d
+
+Purpose:
+  Handle Bluetooth work.
+
 To reduce its OS jitter, do one of the following:
+
 1. Don't use Bluetooth, in which case these kthreads won't be
created in the first place.
 2. Use irq affinity to force Bluetooth-related interrupts to
occur on some other CPU and furthermore initiate all
Bluetooth activity on some other CPU.
 
-Name: ksoftirqd/%u
-Purpose: Execute softirq handlers when threaded or when under heavy load.
+Name:
+  ksoftirqd/%u
+
+Purpose:
+  Execute softirq handlers when threaded or when under heavy load.
+
 To reduce its OS jitter, each softirq vector must be handled
 separately as follows:
-TIMER_SOFTIRQ:  Do all of the following:
+
+TIMER_SOFTIRQ
+-
+
+Do all of the following:
+
 1. To the extent possible, keep the CPU out of the kernel when it
is non-idle, for example, by avoiding system calls and by forcing
both kernel threads and interrupts to execute elsewhere.
@@ -76,34 +102,59 @@ TIMER_SOFTIRQ:  Do all of the following:
first one back online.  Once you have onlined the CPUs in question,
do not offline any other CPUs, because doing so could force the
timer back onto one of the CPUs in question.
-NET_TX_SOFTIRQ and NET_RX_SOFTIRQ:  Do all of the 

[PATCH 05/30] irqflags-tracing.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:

There isn't much to be done here: just mark the document
title as such and add a :Author:.

While here, use upper case at the beginning of a few paragraphs
that start with lower case.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/irqflags-tracing.txt | 10 ++
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/irqflags-tracing.txt 
b/Documentation/irqflags-tracing.txt
index f6da05670e16..bdd208259fb3 100644
--- a/Documentation/irqflags-tracing.txt
+++ b/Documentation/irqflags-tracing.txt
@@ -1,8 +1,10 @@
+===
 IRQ-flags state tracing
+===
 
-started by Ingo Molnar 
+:Author: started by Ingo Molnar 
 
-the "irq-flags tracing" feature "traces" hardirq and softirq state, in
+The "irq-flags tracing" feature "traces" hardirq and softirq state, in
 that it gives interested subsystems an opportunity to be notified of
 every hardirqs-off/hardirqs-on, softirqs-off/softirqs-on event that
 happens in the kernel.
@@ -14,7 +16,7 @@ CONFIG_PROVE_RWSEM_LOCKING will be offered on an architecture 
- these
 are locking APIs that are not used in IRQ context. (the one exception
 for rwsems is worked around)
 
-architecture support for this is certainly not in the "trivial"
+Architecture support for this is certainly not in the "trivial"
 category, because lots of lowlevel assembly code deal with irq-flags
 state changes. But an architecture can be irq-flags-tracing enabled in a
 rather straightforward and risk-free manner.
@@ -41,7 +43,7 @@ irq-flags-tracing support:
   excluded from the irq-tracing [and lock validation] mechanism via
   lockdep_off()/lockdep_on().
 
-in general there is no risk from having an incomplete irq-flags-tracing
+In general there is no risk from having an incomplete irq-flags-tracing
 implementation in an architecture: lockdep will detect that and will
 turn itself off. I.e. the lock validator will still be reliable. There
 should be no crashes due to irq-tracing bugs. (except if the assembly
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 12/30] kref.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 and section titles;
- move authorship information to the beginning and use
  :Author:
- mark literal blocks as such and ident them if needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kref.txt | 285 ++---
 1 file changed, 150 insertions(+), 135 deletions(-)

diff --git a/Documentation/kref.txt b/Documentation/kref.txt
index d26a27ca964d..3af384156d7e 100644
--- a/Documentation/kref.txt
+++ b/Documentation/kref.txt
@@ -1,24 +1,42 @@
+===
+Adding reference counters (krefs) to kernel objects
+===
+
+:Author: Corey Minyard 
+:Author: Thomas Hellstrom 
+
+A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
+presentation on krefs, which can be found at:
+
+  - 
http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
+  - http://www.kroah.com/linux/talks/ols_2004_kref_talk/
+
+Introduction
+
 
 krefs allow you to add reference counters to your objects.  If you
 have objects that are used in multiple places and passed around, and
 you don't have refcounts, your code is almost certainly broken.  If
 you want refcounts, krefs are the way to go.
 
-To use a kref, add one to your data structures like:
+To use a kref, add one to your data structures like::
 
-struct my_data
-{
+struct my_data
+{
.
.
struct kref refcount;
.
.
-};
+};
 
 The kref can occur anywhere within the data structure.
 
+Initialization
+==
+
 You must initialize the kref after you allocate it.  To do this, call
-kref_init as so:
+kref_init as so::
 
  struct my_data *data;
 
@@ -29,18 +47,25 @@ kref_init as so:
 
 This sets the refcount in the kref to 1.
 
+Kref rules
+==
+
 Once you have an initialized kref, you must follow the following
 rules:
 
 1) If you make a non-temporary copy of a pointer, especially if
it can be passed to another thread of execution, you must
-   increment the refcount with kref_get() before passing it off:
+   increment the refcount with kref_get() before passing it off::
+
kref_get(>refcount);
+
If you already have a valid pointer to a kref-ed structure (the
refcount cannot go to zero) you may do this without a lock.
 
-2) When you are done with a pointer, you must call kref_put():
+2) When you are done with a pointer, you must call kref_put()::
+
kref_put(>refcount, data_release);
+
If this is the last reference to the pointer, the release
routine will be called.  If the code never tries to get
a valid pointer to a kref-ed structure without already
@@ -53,25 +78,25 @@ rules:
structure must remain valid during the kref_get().
 
 For example, if you allocate some data and then pass it to another
-thread to process:
+thread to process::
 
-void data_release(struct kref *ref)
-{
+void data_release(struct kref *ref)
+{
struct my_data *data = container_of(ref, struct my_data, refcount);
kfree(data);
-}
+}
 
-void more_data_handling(void *cb_data)
-{
+void more_data_handling(void *cb_data)
+{
struct my_data *data = cb_data;
.
. do stuff with data here
.
kref_put(>refcount, data_release);
-}
+}
 
-int my_data_handler(void)
-{
+int my_data_handler(void)
+{
int rv = 0;
struct my_data *data;
struct task_struct *task;
@@ -91,10 +116,10 @@ int my_data_handler(void)
.
. do stuff with data here
.
- out:
+out:
kref_put(>refcount, data_release);
return rv;
-}
+}
 
 This way, it doesn't matter what order the two threads handle the
 data, the kref_put() handles knowing when the data is not referenced
@@ -104,7 +129,7 @@ put needs no lock because nothing tries to get the data 
without
 already holding a pointer.
 
 Note that the "before" in rule 1 is very important.  You should never
-do something like:
+do something like::
 
task = kthread_run(more_data_handling, data, "more_data_handling");
if (task == ERR_PTR(-ENOMEM)) {
@@ -124,14 +149,14 @@ bad style.  Don't do it.
 There are some situations where you can optimize the gets and puts.
 For instance, if you are done with an object and enqueuing it for
 something else or passing it off to something else, there is no reason
-to do a get then a put:
+to do a get then a put::
 
/* Silly extra get and put */
kref_get(>ref);
enqueue(obj);
kref_put(>ref, obj_cleanup);
 
-Just do the enqueue.  A comment about this is always welcome:
+Just do the enqueue.  A 

[PATCH 00/30] Standardize doc formats - part 2

[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 2.

Mauro Carvalho Chehab (30):
  iostats.txt: update it to cover recent Kernels
  IPMI.txt: standardize document format
  IRQ-affinity.txt: standardize document format
  IRQ-domain.txt: standardize document format
  irqflags-tracing.txt: standardize document format
  IRQ.txt: add a markup for its title
  isapnp.txt: promote title level
  isa.txt: standardize document format
  kernel-per-CPU-kthreads.txt: standardize document format
  kobject.txt: standardize document format
  kprobes.txt: standardize document format
  kref.txt: standardize document format
  kselftest.txt: standardize document format
  ldm.txt: standardize document format
  lockup-watchdogs.txt: standardize document format
  lzo.txt: standardize document format
  mailbox.txt: standardize document format
  memory-barriers.txt: standardize document format
  memory-barriers.txt: use literals for variables
  memory-hotplug.txt: standardize document format
  men-chameleon-bus.txt: standardize document format
  nommu-mmap.txt: standardize document format
  nommu-mmap.txt: don't use all upper case on titles
  ntb.txt: standardize document format
  numastat.txt: standardize document format
  padata.txt: standardize document format
  parport-lowlevel.txt: standardize document format
  percpu-rw-semaphore.txt: standardize document format
  phy.txt: standardize document format
  pi-futex.txt: standardize document format

 Documentation/IPMI.txt|   76 +-
 Documentation/IRQ-affinity.txt|   77 +-
 Documentation/IRQ-domain.txt  |   69 +-
 Documentation/IRQ.txt |2 +
 Documentation/iostats.txt |   44 +-
 Documentation/irqflags-tracing.txt|   10 +-
 Documentation/isa.txt |   53 +-
 Documentation/isapnp.txt  |1 +
 Documentation/kernel-per-CPU-kthreads.txt |  156 +++-
 Documentation/kobject.txt |   69 +-
 Documentation/kprobes.txt |  450 ++
 Documentation/kref.txt|  285 ---
 Documentation/kselftest.txt   |   37 +-
 Documentation/ldm.txt |   54 +-
 Documentation/lockup-watchdogs.txt|3 +-
 Documentation/lzo.txt |   27 +-
 Documentation/mailbox.txt |  181 ++--
 Documentation/memory-barriers.txt |  794 +-
 Documentation/memory-hotplug.txt  |  357 
 Documentation/men-chameleon-bus.txt   |  298 +++
 Documentation/nommu-mmap.txt  |   68 +-
 Documentation/ntb.txt |   55 +-
 Documentation/numastat.txt|5 +-
 Documentation/padata.txt  |   27 +-
 Documentation/parport-lowlevel.txt| 1303 ++---
 Documentation/percpu-rw-semaphore.txt |3 +-
 Documentation/phy.txt |  106 ++-
 Documentation/pi-futex.txt|   15 +-
 28 files changed, 2683 insertions(+), 1942 deletions(-)

-- 
2.9.4


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 08/30] isa.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 the main title standard for this document;
- replace _foo_ by **foo** for emphasis;
- mark literal blocks as such.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/isa.txt | 53 ++-
 1 file changed, 27 insertions(+), 26 deletions(-)

diff --git a/Documentation/isa.txt b/Documentation/isa.txt
index f232c26a40be..def4a7b690b5 100644
--- a/Documentation/isa.txt
+++ b/Documentation/isa.txt
@@ -1,5 +1,6 @@
+===
 ISA Drivers

+===
 
 The following text is adapted from the commit message of the initial
 commit of the ISA bus driver authored by Rene Herman.
@@ -23,17 +24,17 @@ that all device creation has been made internal as well.
 
 The usage model this provides is nice, and has been acked from the ALSA
 side by Takashi Iwai and Jaroslav Kysela. The ALSA driver module_init's
-now (for oldisa-only drivers) become:
+now (for oldisa-only drivers) become::
 
-static int __init alsa_card_foo_init(void)
-{
-   return isa_register_driver(_foo_isa_driver, SNDRV_CARDS);
-}
+   static int __init alsa_card_foo_init(void)
+   {
+   return isa_register_driver(_foo_isa_driver, SNDRV_CARDS);
+   }
 
-static void __exit alsa_card_foo_exit(void)
-{
-   isa_unregister_driver(_foo_isa_driver);
-}
+   static void __exit alsa_card_foo_exit(void)
+   {
+   isa_unregister_driver(_foo_isa_driver);
+   }
 
 Quite like the other bus models therefore. This removes a lot of
 duplicated init code from the ALSA ISA drivers.
@@ -47,11 +48,11 @@ parameter, indicating how many devices to create and call 
our methods
 with.
 
 The platform_driver callbacks are called with a platform_device param;
-the isa_driver callbacks are being called with a "struct device *dev,
-unsigned int id" pair directly -- with the device creation completely
+the isa_driver callbacks are being called with a ``struct device *dev,
+unsigned int id`` pair directly -- with the device creation completely
 internal to the bus it's much cleaner to not leak isa_dev's by passing
 them in at all. The id is the only thing we ever want other then the
-struct device * anyways, and it makes for nicer code in the callbacks as
+struct device anyways, and it makes for nicer code in the callbacks as
 well.
 
 With this additional .match() callback ISA drivers have all options. If
@@ -75,20 +76,20 @@ This exports only two functions; isa_{,un}register_driver().
 
 isa_register_driver() register's the struct device_driver, and then
 loops over the passed in ndev creating devices and registering them.
-This causes the bus match method to be called for them, which is:
+This causes the bus match method to be called for them, which is::
 
-int isa_bus_match(struct device *dev, struct device_driver *driver)
-{
-  struct isa_driver *isa_driver = to_isa_driver(driver);
+   int isa_bus_match(struct device *dev, struct device_driver *driver)
+   {
+   struct isa_driver *isa_driver = to_isa_driver(driver);
 
-  if (dev->platform_data == isa_driver) {
-  if (!isa_driver->match ||
-  isa_driver->match(dev, to_isa_dev(dev)->id))
-  return 1;
-  dev->platform_data = NULL;
-  }
-  return 0;
-}
+   if (dev->platform_data == isa_driver) {
+   if (!isa_driver->match ||
+   isa_driver->match(dev, to_isa_dev(dev)->id))
+   return 1;
+   dev->platform_data = NULL;
+   }
+   return 0;
+   }
 
 The first thing this does is check if this device is in fact one of this
 driver's devices by seeing if the device's platform_data pointer is set
@@ -102,7 +103,7 @@ well.
 Then, if the the driver did not provide a .match, it matches. If it did,
 the driver match() method is called to determine a match.
 
-If it did _not_ match, dev->platform_data is reset to indicate this to
+If it did **not** match, dev->platform_data is reset to indicate this to
 isa_register_driver which can then unregister the device again.
 
 If during all this, there's any error, or no devices matched at all
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 19/30] memory-barriers.txt: use literals for variables

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab 

The minimal adjustments on this file were not enough
to make it build clean with Sphinx:

  Documentation/memory-barriers.rst:192: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:603: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:1065: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:1068: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:2289: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:2289: WARNING: Inline emphasis start-string 
without end-string.
  Documentation/memory-barriers.rst:3091: WARNING: Inline emphasis start-string 
without end-string.

What happens there is that, while some vars are inside
'var' or `var`, most of them aren't, and some start with
asterisk.

Standardize it by always use ``literal``. As a bonus,
the output will use the same monospaced fonts as the
literal blocks.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/memory-barriers.txt | 154 +++---
 1 file changed, 77 insertions(+), 77 deletions(-)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index f37b418b3022..df3438ba49c6 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -181,16 +181,16 @@ As a further example, consider this sequence of events::
B = 4;  Q = P;
P =   D = *Q;
 
-There is an obvious data dependency here, as the value loaded into D depends on
-the address retrieved from P by CPU 2.  At the end of the sequence, any of the
+There is an obvious data dependency here, as the value loaded into ``D`` 
depends on
+the address retrieved from ``P`` by CPU 2.  At the end of the sequence, any of 
the
 following results are possible::
 
(Q == ) and (D == 1)
(Q == ) and (D == 2)
(Q == ) and (D == 4)
 
-Note that CPU 2 will never try and load C into D because the CPU will load P
-into Q before issuing the load of *Q.
+Note that CPU 2 will never try and load ``C`` into ``D`` because the CPU will 
load ``P``
+into ``Q`` before issuing the load of ``*Q``.
 
 
 Device operations
@@ -199,8 +199,8 @@ Device operations
 Some devices present their control interfaces as collections of memory
 locations, but the order in which the control registers are accessed is very
 important.  For instance, imagine an ethernet card with a set of internal
-registers that are accessed through an address port register (A) and a data
-port register (D).  To read internal register 5, the following code might then
+registers that are accessed through an address port register (``A``) and a data
+port register (``D``).  To read internal register 5, the following code might 
then
 be used::
 
*A = 5;
@@ -558,12 +558,12 @@ following sequence of events::
  D = *Q;
 
 There's a clear data dependency here, and it would seem that by the end of the
-sequence, Q must be either  or , and that::
+sequence, ``Q`` must be either  or , and that::
 
(Q == ) implies (D == 1)
(Q == ) implies (D == 4)
 
-But!  CPU 2's perception of P may be updated _before_ its perception of B, thus
+But!  CPU 2's perception of ``P`` may be updated _before_ its perception of 
``B``, thus
 leading to the following situation::
 
(Q == ) and (D == 2) 
@@ -600,8 +600,8 @@ A data-dependency barrier must also order against dependent 
writes::
  
  *Q = 5;
 
-The data-dependency barrier must order the read into Q with the store
-into *Q.  This prohibits this outcome::
+The data-dependency barrier must order the read into ``Q`` with the store
+into ``*Q``.  This prohibits this outcome::
 
(Q == ) && (B == 4)
 
@@ -615,11 +615,11 @@ prevents such records from being lost.
 [!] Note that this extremely counterintuitive situation arises most easily on
 machines with split caches, so that, for example, one cache bank processes
 even-numbered cache lines and the other bank processes odd-numbered cache
-lines.  The pointer P might be stored in an odd-numbered cache line, and the
-variable B might be stored in an even-numbered cache line.  Then, if the
+lines.  The pointer ``P`` might be stored in an odd-numbered cache line, and 
the
+variable ``B`` might be stored in an even-numbered cache line.  Then, if the
 even-numbered bank of the reading CPU's cache is extremely busy while the
-odd-numbered bank is idle, one can see the new value of the pointer P (),
-but the old value of the variable B (2).
+odd-numbered bank is idle, one can see the new value of the pointer ``P`` 
(),
+but the old value of the variable ``B`` (2).
 

[PATCH 25/30] numastat.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 document title;
- mark the table as such.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/numastat.txt | 5 -
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/numastat.txt b/Documentation/numastat.txt
index 520327790d54..aaf1667489f8 100644
--- a/Documentation/numastat.txt
+++ b/Documentation/numastat.txt
@@ -1,10 +1,12 @@
-
+===
 Numa policy hit/miss statistics
+===
 
 /sys/devices/system/node/node*/numastat
 
 All units are pages. Hugepages have separate counters.
 
+=== 
 numa_hit   A process wanted to allocate memory from this node,
and succeeded.
 
@@ -20,6 +22,7 @@ other_nodeA process ran on this node and got memory from 
another node.
 
 interleave_hit Interleaving wanted to allocate from this node
and succeeded.
+=== 
 
 For easier reading you can use the numastat utility from the numactl package
 (http://oss.sgi.com/projects/libnuma/). Note that it only works
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 06/30] IRQ.txt: add a markup for its title

[Mauro Carvalho Chehab]

This simple document only needs a markup for its title to be
using the standard we're adopting for text documents.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/IRQ.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.txt
index 1011e7175021..4273806a606b 100644
--- a/Documentation/IRQ.txt
+++ b/Documentation/IRQ.txt
@@ -1,4 +1,6 @@
+===
 What is an IRQ?
+===
 
 An IRQ is an interrupt request from a device.
 Currently they can come in over a pin, or over a packet.
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 23/30] nommu-mmap.txt: don't use all upper case on titles

[Mauro Carvalho Chehab]

This file is almost in the standard format we're adopting for
other documentation text files. Yet, it use upper case on
titles.

So, in order to uniform how chapter names, adjust caps on
titles.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/nommu-mmap.txt | 18 +-
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.txt
index 39a62ab0f50a..69556f0d494b 100644
--- a/Documentation/nommu-mmap.txt
+++ b/Documentation/nommu-mmap.txt
@@ -1,5 +1,5 @@
 =
-NO-MMU MEMORY MAPPING SUPPORT
+No-MMU memory mapping support
 =
 
 The kernel has limited support for memory mapping under no-MMU conditions, such
@@ -105,7 +105,7 @@ and it's also much more restricted in the latter case:
provide any such support, then the mapping request will be denied.
 
 
-FURTHER NOTES ON NO-MMU MMAP
+Further notes on no-MMU MMAP
 
 
  (#) A request for a private mapping of a file may return a buffer that is not
@@ -160,7 +160,7 @@ FURTHER NOTES ON NO-MMU MMAP
  with character device files, pipes, fifos and sockets.
 
 
-INTERPROCESS SHARED MEMORY
+Interprocess shared memory
 ==
 
 Both SYSV IPC SHM shared memory and POSIX shared memory is supported in NOMMU
@@ -168,7 +168,7 @@ mode.  The former through the usual mechanism, the latter 
through files created
 on ramfs or tmpfs mounts.
 
 
-FUTEXES
+Futexes
 ===
 
 Futexes are supported in NOMMU mode if the arch supports them.  An error will
@@ -177,7 +177,7 @@ mappings made by a process or if the mapping in which the 
address lies does not
 support futexes (such as an I/O chardev mapping).
 
 
-NO-MMU MREMAP
+No-MMU mremap
 =
 
 The mremap() function is partially supported.  It may change the size of a
@@ -199,7 +199,7 @@ act on a complete mapping.
 .. [#] Not currently supported.
 
 
-PROVIDING SHAREABLE CHARACTER DEVICE SUPPORT
+Providing shareable character device support
 
 
 To provide shareable character device support, a driver must provide a
@@ -244,7 +244,7 @@ copy mapped otherwise.
circumstances!
 
 
-PROVIDING SHAREABLE MEMORY-BACKED FILE SUPPORT
+Providing shareable memory-backed file support
 ==
 
 Provision of shared mappings on memory backed files is similar to the provision
@@ -261,7 +261,7 @@ Memory backed devices are indicated by the mapping's 
backing device info having
 the memory_backed flag set.
 
 
-PROVIDING SHAREABLE BLOCK DEVICE SUPPORT
+Providing shareable block device support
 
 
 Provision of shared mappings on block device files is exactly the same as for
@@ -269,7 +269,7 @@ character devices. If there isn't a real device underneath, 
then the driver
 should allocate sufficient contiguous memory to honour any supported mapping.
 
 
-ADJUSTING PAGE TRIMMING BEHAVIOUR
+Adjusting page trimming behaviour
 =
 
 NOMMU mmap automatically rounds up to the nearest power-of-2 number of pages
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 04/30] IRQ-domain.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 proper markups for titles;
- mark literal blocks as such;
- add blank lines where needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/IRQ-domain.txt | 69 +++-
 1 file changed, 49 insertions(+), 20 deletions(-)

diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt
index 82001a25a14b..ef32ec0f2b04 100644
--- a/Documentation/IRQ-domain.txt
+++ b/Documentation/IRQ-domain.txt
@@ -1,4 +1,6 @@
-irq_domain interrupt number mapping library
+===
+The irq_domain interrupt number mapping library
+===
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
@@ -36,7 +38,9 @@ irq_domain also implements translation from an abstract 
irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-=== irq_domain usage ===
+irq_domain usage
+
+
 An interrupt controller driver creates and registers an irq_domain by
 calling one of the irq_domain_add_*() functions (each mapping method
 has a different allocator function, more on that later).  The function
@@ -62,15 +66,21 @@ If the driver has the Linux IRQ number or the irq_data 
pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-=== Types of irq_domain mappings ===
+Types of irq_domain mappings
+
+
 There are several mechanisms available for reverse mapping from hwirq
 to Linux irq, and each mechanism uses a different allocation function.
 Which reverse map type should be used depends on the use case.  Each
 of the reverse map types are described below:
 
- Linear 
-irq_domain_add_linear()
-irq_domain_create_linear()
+Linear
+--
+
+::
+
+   irq_domain_add_linear()
+   irq_domain_create_linear()
 
 The linear reverse map maintains a fixed size table indexed by the
 hwirq number.  When a hwirq is mapped, an irq_desc is allocated for
@@ -89,9 +99,13 @@ accepts a more general abstraction 'struct fwnode_handle'.
 
 The majority of drivers should use the linear map.
 
- Tree 
-irq_domain_add_tree()
-irq_domain_create_tree()
+Tree
+
+
+::
+
+   irq_domain_add_tree()
+   irq_domain_create_tree()
 
 The irq_domain maintains a radix tree map from hwirq numbers to Linux
 IRQs.  When an hwirq is mapped, an irq_desc is allocated and the
@@ -109,8 +123,12 @@ accepts a more general abstraction 'struct fwnode_handle'.
 
 Very few drivers should need this mapping.
 
- No Map ===-
-irq_domain_add_nomap()
+No Map
+--
+
+::
+
+   irq_domain_add_nomap()
 
 The No Map mapping is to be used when the hwirq number is
 programmable in the hardware.  In this case it is best to program the
@@ -121,10 +139,14 @@ Linux IRQ number into the hardware.
 
 Most drivers cannot use this mapping.
 
- Legacy 
-irq_domain_add_simple()
-irq_domain_add_legacy()
-irq_domain_add_legacy_isa()
+Legacy
+--
+
+::
+
+   irq_domain_add_simple()
+   irq_domain_add_legacy()
+   irq_domain_add_legacy_isa()
 
 The Legacy mapping is a special case for drivers that already have a
 range of irq_descs allocated for the hwirqs.  It is used when the
@@ -163,14 +185,17 @@ that the driver using the simple domain call 
irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
- Hierarchy IRQ domain 
+Hierarchy IRQ domain
+
+
 On some architectures, there may be multiple interrupt controllers
 involved in delivering an interrupt from the device to the target CPU.
-Let's look at a typical interrupt delivering path on x86 platforms:
+Let's look at a typical interrupt delivering path on x86 platforms::
 
-Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
+  Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
 
 There are three interrupt controllers involved:
+
 1) IOAPIC controller
 2) Interrupt remapping controller
 3) Local APIC controller
@@ -180,7 +205,8 @@ hardware architecture, an irq_domain data structure is 
built for each
 interrupt controller and those irq_domains are organized into hierarchy.
 When building irq_domain hierarchy, the irq_domain near to the device is
 child and the irq_domain near to CPU is parent. So a hierarchy structure
-as below will be built for the example above.
+as below will be built for the example above::
+
CPU Vector irq_domain (root irq_domain to manage CPU vectors)

[PATCH 07/30] isapnp.txt: promote title level

[Mauro Carvalho Chehab]

This simple document only needs to promote its title to be
using the standard we're using for document texts.

Yet, IMHO, it would be worth merging this file with
Documentation/pnp.txt in the future.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/isapnp.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/isapnp.txt b/Documentation/isapnp.txt
index 400d1b5b523d..8d0840ac847b 100644
--- a/Documentation/isapnp.txt
+++ b/Documentation/isapnp.txt
@@ -1,3 +1,4 @@
+==
 ISA Plug & Play support by Jaroslav Kysela 
 ==
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 21/30] men-chameleon-bus.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 identations;
- Remove title numbering;
- mark literal blocks;
- comment its TOC.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/men-chameleon-bus.txt | 298 +++-
 1 file changed, 155 insertions(+), 143 deletions(-)

diff --git a/Documentation/men-chameleon-bus.txt 
b/Documentation/men-chameleon-bus.txt
index 30ded732027e..1b1f048aa748 100644
--- a/Documentation/men-chameleon-bus.txt
+++ b/Documentation/men-chameleon-bus.txt
@@ -1,163 +1,175 @@
-   MEN Chameleon Bus
-   =
-
-Table of Contents
 =
-1 Introduction
-1.1 Scope of this Document
-1.2 Limitations of the current implementation
-2 Architecture
-2.1 MEN Chameleon Bus
-2.2 Carrier Devices
-2.3 Parser
-3 Resource handling
-3.1 Memory Resources
-3.2 IRQs
-4 Writing an MCB driver
-4.1 The driver structure
-4.2 Probing and attaching
-4.3 Initializing the driver
-
+MEN Chameleon Bus
+=
 
-1 Introduction
-===
-  This document describes the architecture and implementation of the MEN
-  Chameleon Bus (called MCB throughout this document).
+.. Table of Contents
+   =
+   1 Introduction
+   1.1 Scope of this Document
+   1.2 Limitations of the current implementation
+   2 Architecture
+   2.1 MEN Chameleon Bus
+   2.2 Carrier Devices
+   2.3 Parser
+   3 Resource handling
+   3.1 Memory Resources
+   3.2 IRQs
+   4 Writing an MCB driver
+   4.1 The driver structure
+   4.2 Probing and attaching
+   4.3 Initializing the driver
 
-1.1 Scope of this Document

-  This document is intended to be a short overview of the current
-  implementation and does by no means describe the complete possibilities of 
MCB
-  based devices.
 
-1.2 Limitations of the current implementation
---
-  The current implementation is limited to PCI and PCIe based carrier devices
-  that only use a single memory resource and share the PCI legacy IRQ.  Not
-  implemented are:
-  - Multi-resource MCB devices like the VME Controller or M-Module carrier.
-  - MCB devices that need another MCB device, like SRAM for a DMA Controller's
-buffer descriptors or a video controller's video memory.
-  - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs
-per MCB device like PCIe based carriers with MSI or MSI-X support.
+Introduction
+
 
-2 Architecture
-===
-  MCB is divided into 3 functional blocks:
-  - The MEN Chameleon Bus itself,
-  - drivers for MCB Carrier Devices and
-  - the parser for the Chameleon table.
+This document describes the architecture and implementation of the MEN
+Chameleon Bus (called MCB throughout this document).
 
-2.1 MEN Chameleon Bus
+Scope of this Document
 --
-   The MEN Chameleon Bus is an artificial bus system that attaches to a so
-   called Chameleon FPGA device found on some hardware produced my MEN Mikro
-   Elektronik GmbH. These devices are multi-function devices implemented in a
-   single FPGA and usually attached via some sort of PCI or PCIe link. Each
-   FPGA contains a header section describing the content of the FPGA. The
-   header lists the device id, PCI BAR, offset from the beginning of the PCI
-   BAR, size in the FPGA, interrupt number and some other properties currently
-   not handled by the MCB implementation.
-
-2.2 Carrier Devices
+
+This document is intended to be a short overview of the current
+implementation and does by no means describe the complete possibilities of MCB
+based devices.
+
+Limitations of the current implementation
+-
+
+The current implementation is limited to PCI and PCIe based carrier devices
+that only use a single memory resource and share the PCI legacy IRQ.  Not
+implemented are:
+
+- Multi-resource MCB devices like the VME Controller or M-Module carrier.
+- MCB devices that need another MCB device, like SRAM for a DMA Controller's
+  buffer descriptors or a video controller's video memory.
+- A per-carrier IRQ domain for carrier devices that have one (or more) IRQs
+  per MCB device like PCIe based carriers with MSI or MSI-X support.
+
+Architecture
+
+
+MCB is divided into 3 functional blocks:
+
+- The MEN Chameleon Bus itself,
+- drivers for MCB Carrier Devices and
+- the parser for the Chameleon table.
+
+MEN Chameleon Bus
+-
+
+The MEN Chameleon Bus is an artificial bus system that attaches to a so
+called Chameleon FPGA device found on some hardware produced my MEN Mikro
+Elektronik GmbH. These devices are 

[PATCH 17/30] mailbox.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 markups for section titles;
- Use :Author: for authorship;
- Mark literal block as such and ident it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/mailbox.txt | 181 --
 1 file changed, 95 insertions(+), 86 deletions(-)

diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.txt
index 7ed371c85204..0ed95009cc30 100644
--- a/Documentation/mailbox.txt
+++ b/Documentation/mailbox.txt
@@ -1,7 +1,10 @@
-   The Common Mailbox Framework
-   Jassi Brar 
+
+The Common Mailbox Framework
+
 
- This document aims to help developers write client and controller
+:Author: Jassi Brar 
+
+This document aims to help developers write client and controller
 drivers for the API. But before we start, let us note that the
 client (especially) and controller drivers are likely going to be
 very platform specific because the remote firmware is likely to be
@@ -13,14 +16,17 @@ similar copies of code written for each platform. Having 
said that,
 nothing prevents the remote f/w to also be Linux based and use the
 same api there. However none of that helps us locally because we only
 ever deal at client's protocol level.
- Some of the choices made during implementation are the result of this
+
+Some of the choices made during implementation are the result of this
 peculiarity of this "common" framework.
 
 
 
-   Part 1 - Controller Driver (See include/linux/mailbox_controller.h)
+Controller Driver (See include/linux/mailbox_controller.h)
+==
 
- Allocate mbox_controller and the array of mbox_chan.
+
+Allocate mbox_controller and the array of mbox_chan.
 Populate mbox_chan_ops, except peek_data() all are mandatory.
 The controller driver might know a message has been consumed
 by the remote by getting an IRQ or polling some hardware flag
@@ -30,91 +36,94 @@ the controller driver should set via 'txdone_irq' or 
'txdone_poll'
 or neither.
 
 
-   Part 2 - Client Driver (See include/linux/mailbox_client.h)
+Client Driver (See include/linux/mailbox_client.h)
+==
 
- The client might want to operate in blocking mode (synchronously
+
+The client might want to operate in blocking mode (synchronously
 send a message through before returning) or non-blocking/async mode (submit
 a message and a callback function to the API and return immediately).
 
+::
 
-struct demo_client {
-   struct mbox_client cl;
-   struct mbox_chan *mbox;
-   struct completion c;
-   bool async;
-   /* ... */
-};
+   struct demo_client {
+   struct mbox_client cl;
+   struct mbox_chan *mbox;
+   struct completion c;
+   bool async;
+   /* ... */
+   };
 
-/*
- * This is the handler for data received from remote. The behaviour is purely
- * dependent upon the protocol. This is just an example.
- */
-static void message_from_remote(struct mbox_client *cl, void *mssg)
-{
-   struct demo_client *dc = container_of(cl, struct demo_client, cl);
-   if (dc->async) {
-   if (is_an_ack(mssg)) {
-   /* An ACK to our last sample sent */
-   return; /* Or do something else here */
-   } else { /* A new message from remote */
-   queue_req(mssg);
+   /*
+   * This is the handler for data received from remote. The behaviour is 
purely
+   * dependent upon the protocol. This is just an example.
+   */
+   static void message_from_remote(struct mbox_client *cl, void *mssg)
+   {
+   struct demo_client *dc = container_of(cl, struct demo_client, 
cl);
+   if (dc->async) {
+   if (is_an_ack(mssg)) {
+   /* An ACK to our last sample sent */
+   return; /* Or do something else here */
+   } else { /* A new message from remote */
+   queue_req(mssg);
+   }
+   } else {
+   /* Remote f/w sends only ACK packets on this channel */
+   return;
}
-   } else {
-   /* Remote f/w sends only ACK packets on this channel */
-   return;
}
-}
-
-static void sample_sent(struct mbox_client *cl, void *mssg, int r)
-{
-   struct demo_client *dc = container_of(cl, struct demo_client, cl);
-   complete(>c);
-}
-
-static void client_demo(struct platform_device *pdev)
-{
-   struct 

[PATCH 22/30] nommu-mmap.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 for main title;
- fix level for chapter titles;
- use ".. important::" tag for an important note;
- use the right notation for paragraph auto-numbering "(#)";
- Fix footnotes syntax;
- fix one literal var to use the right ReST tag.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/nommu-mmap.txt | 52 +++-
 1 file changed, 22 insertions(+), 30 deletions(-)

diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.txt
index ae57b9ea0d41..39a62ab0f50a 100644
--- a/Documentation/nommu-mmap.txt
+++ b/Documentation/nommu-mmap.txt
@@ -1,6 +1,6 @@
-=
-NO-MMU MEMORY MAPPING SUPPORT
-=
+=
+NO-MMU MEMORY MAPPING SUPPORT
+=
 
 The kernel has limited support for memory mapping under no-MMU conditions, such
 as are used in uClinux environments. From the userspace point of view, memory
@@ -16,7 +16,7 @@ the CLONE_VM flag.
 The behaviour is similar between the MMU and no-MMU cases, but not identical;
 and it's also much more restricted in the latter case:
 
- (*) Anonymous mapping, MAP_PRIVATE
+ (#) Anonymous mapping, MAP_PRIVATE
 
In the MMU case: VM regions backed by arbitrary pages; copy-on-write
across fork.
@@ -24,14 +24,14 @@ and it's also much more restricted in the latter case:
In the no-MMU case: VM regions backed by arbitrary contiguous runs of
pages.
 
- (*) Anonymous mapping, MAP_SHARED
+ (#) Anonymous mapping, MAP_SHARED
 
These behave very much like private mappings, except that they're
shared across fork() or clone() without CLONE_VM in the MMU case. Since
the no-MMU case doesn't support these, behaviour is identical to
MAP_PRIVATE there.
 
- (*) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, !PROT_WRITE
+ (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, !PROT_WRITE
 
In the MMU case: VM regions backed by pages read from file; changes to
the underlying file are reflected in the mapping; copied across fork.
@@ -56,7 +56,7 @@ and it's also much more restricted in the latter case:
   are visible in other processes (no MMU protection), but should not
   happen.
 
- (*) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, PROT_WRITE
+ (#) File, MAP_PRIVATE, PROT_READ / PROT_EXEC, PROT_WRITE
 
In the MMU case: like the non-PROT_WRITE case, except that the pages in
question get copied before the write actually happens. From that point
@@ -66,7 +66,7 @@ and it's also much more restricted in the latter case:
In the no-MMU case: works much like the non-PROT_WRITE case, except
that a copy is always taken and never shared.
 
- (*) Regular file / blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
+ (#) Regular file / blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
 
In the MMU case: VM regions backed by pages read from file; changes to
pages written back to file; writes to file reflected into pages backing
@@ -74,7 +74,7 @@ and it's also much more restricted in the latter case:
 
In the no-MMU case: not supported.
 
- (*) Memory backed regular file, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
+ (#) Memory backed regular file, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
 
In the MMU case: As for ordinary regular files.
 
@@ -85,7 +85,7 @@ and it's also much more restricted in the latter case:
as for the MMU case. If the filesystem does not provide any such
support, then the mapping request will be denied.
 
- (*) Memory backed blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
+ (#) Memory backed blockdev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
 
In the MMU case: As for ordinary regular files.
 
@@ -94,7 +94,7 @@ and it's also much more restricted in the latter case:
truncate being called. The ramdisk driver could do this if it allocated
all its memory as a contiguous array upfront.
 
- (*) Memory backed chardev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
+ (#) Memory backed chardev, MAP_SHARED, PROT_READ / PROT_EXEC / PROT_WRITE
 
In the MMU case: As for ordinary regular files.
 
@@ -105,21 +105,20 @@ and it's also much more restricted in the latter case:
provide any such support, then the mapping request will be denied.
 
 
-
 FURTHER NOTES ON NO-MMU MMAP
 
 
- (*) A request for a private mapping of a file may return a buffer that is not
+ (#) A request for a private mapping of a file may return a buffer that is not
  page-aligned.  This is 

[PATCH 30/30] pi-futex.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 requires just minor adjustments to match
the standard documentation style:

- promote document name;
- remove extra collons on some chapter titles;
- use "-" for a bulleted list.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/pi-futex.txt | 15 ---
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt
index 9a5bc8651c29..aafddbee7377 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.txt
@@ -1,5 +1,6 @@
+==
 Lightweight PI-futexes
---
+==
 
 We are calling them lightweight for 3 reasons:
 
@@ -25,8 +26,8 @@ determinism and well-bound latencies. Even in the worst-case, 
PI will
 improve the statistical distribution of locking related application
 delays.
 
-The longer reply:
--
+The longer reply
+
 
 Firstly, sharing locks between multiple tasks is a common programming
 technique that often cannot be replaced with lockless algorithms. As we
@@ -71,8 +72,8 @@ deterministic execution of the high-prio task: any 
medium-priority task
 could preempt the low-prio task while it holds the shared lock and
 executes the critical section, and could delay it indefinitely.
 
-Implementation:

+Implementation
+--
 
 As mentioned before, the userspace fastpath of PI-enabled pthread
 mutexes involves no kernel work at all - they behave quite similarly to
@@ -83,8 +84,8 @@ entering the kernel.
 
 To handle the slowpath, we have added two new futex ops:
 
-  FUTEX_LOCK_PI
-  FUTEX_UNLOCK_PI
+  - FUTEX_LOCK_PI
+  - FUTEX_UNLOCK_PI
 
 If the lock-acquire fastpath fails, [i.e. an atomic transition from 0 to
 TID fails], then FUTEX_LOCK_PI is called. The kernel does all the
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 26/30] padata.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.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/padata.txt | 27 +++
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/Documentation/padata.txt b/Documentation/padata.txt
index 7ddfe216a0aa..b103d0c82000 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.txt
@@ -1,5 +1,8 @@
+===
 The padata parallel execution mechanism
-Last updated for 2.6.36
+===
+
+:Last updated: for 2.6.36
 
 Padata is a mechanism by which the kernel can farm work out to be done in
 parallel on multiple CPUs while retaining the ordering of tasks.  It was
@@ -9,7 +12,7 @@ those packets.  The crypto developers made a point of writing 
padata in a
 sufficiently general fashion that it could be put to other uses as well.
 
 The first step in using padata is to set up a padata_instance structure for
-overall control of how tasks are to be run:
+overall control of how tasks are to be run::
 
 #include 
 
@@ -24,7 +27,7 @@ The workqueue wq is where the work will actually be done; it 
should be
 a multithreaded queue, naturally.
 
 To allocate a padata instance with the cpu_possible_mask for both
-cpumasks this helper function can be used:
+cpumasks this helper function can be used::
 
 struct padata_instance *padata_alloc_possible(struct workqueue_struct *wq);
 
@@ -36,7 +39,7 @@ it is legal to supply a cpumask to padata that contains 
offline CPUs.
 Once an offline CPU in the user supplied cpumask comes online, padata
 is going to use it.
 
-There are functions for enabling and disabling the instance:
+There are functions for enabling and disabling the instance::
 
 int padata_start(struct padata_instance *pinst);
 void padata_stop(struct padata_instance *pinst);
@@ -48,7 +51,7 @@ padata cpumask contains no active CPU (flag not set).
 padata_stop clears the flag and blocks until the padata instance
 is unused.
 
-The list of CPUs to be used can be adjusted with these functions:
+The list of CPUs to be used can be adjusted with these functions::
 
 int padata_set_cpumasks(struct padata_instance *pinst,
cpumask_var_t pcpumask,
@@ -71,12 +74,12 @@ padata_add_cpu/padata_remove_cpu are used. cpu specifies 
the CPU to add or
 remove and mask is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL.
 
 If a user is interested in padata cpumask changes, he can register to
-the padata cpumask change notifier:
+the padata cpumask change notifier::
 
 int padata_register_cpumask_notifier(struct padata_instance *pinst,
 struct notifier_block *nblock);
 
-To unregister from that notifier:
+To unregister from that notifier::
 
 int padata_unregister_cpumask_notifier(struct padata_instance *pinst,
   struct notifier_block *nblock);
@@ -84,7 +87,7 @@ To unregister from that notifier:
 The padata cpumask change notifier notifies about changes of the usable
 cpumasks, i.e. the subset of active CPUs in the user supplied cpumask.
 
-Padata calls the notifier chain with:
+Padata calls the notifier chain with::
 
 blocking_notifier_call_chain(>cpumask_change_notifier,
 notification_mask,
@@ -95,7 +98,7 @@ is one of PADATA_CPU_SERIAL, PADATA_CPU_PARALLEL and cpumask 
is a pointer
 to a struct padata_cpumask that contains the new cpumask information.
 
 Actually submitting work to the padata instance requires the creation of a
-padata_priv structure:
+padata_priv structure::
 
 struct padata_priv {
 /* Other stuff here... */
@@ -110,7 +113,7 @@ parallel() and serial() functions should be provided.  
Those functions will
 be called in the process of getting the work done as we will see
 momentarily.
 
-The submission of work is done with:
+The submission of work is done with::
 
 int padata_do_parallel(struct padata_instance *pinst,
   struct padata_priv *padata, int cb_cpu);
@@ -138,7 +141,7 @@ need not be completed during this call, but, if parallel() 
leaves work
 outstanding, it should be prepared to be called again with a new job before
 the previous one completes.  When a task does complete, parallel() (or
 whatever function actually finishes the job) should inform padata of the
-fact with a call to:
+fact with a call to::
 
 void padata_do_serial(struct padata_priv *padata);
 
@@ -151,7 +154,7 @@ pains to ensure that tasks are completed in the order in 
which they were
 submitted.
 
 The one remaining function in the padata API should be called to clean up
-when a padata instance is no longer needed:
+when a padata instance is no longer needed::
 
  

[PATCH 11/30] kprobes.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:

- comment the contents;
- add proper markups for titles;
- mark literal blocks as such;
- use :Author: for authorship;
- use the right markups for footnotes;
- escape some literals that would otherwise cause problems;
- fix identation and add blank lines where needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/kprobes.txt | 450 +++---
 1 file changed, 265 insertions(+), 185 deletions(-)

diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt
index 1f6d45abfe42..48146e093b1a 100644
--- a/Documentation/kprobes.txt
+++ b/Documentation/kprobes.txt
@@ -1,30 +1,36 @@
-Title  : Kernel Probes (Kprobes)
-Authors: Jim Keniston 
-   : Prasanna S Panchamukhi 
-   : Masami Hiramatsu 
+===
+Kernel Probes (Kprobes)
+===
 
-CONTENTS
+:Author: Jim Keniston 
+:Author: Prasanna S Panchamukhi 
+:Author: Masami Hiramatsu 
 
-1. Concepts: Kprobes, Jprobes, Return Probes
-2. Architectures Supported
-3. Configuring Kprobes
-4. API Reference
-5. Kprobes Features and Limitations
-6. Probe Overhead
-7. TODO
-8. Kprobes Example
-9. Jprobes Example
-10. Kretprobes Example
-Appendix A: The kprobes debugfs interface
-Appendix B: The kprobes sysctl interface
+.. CONTENTS
 
-1. Concepts: Kprobes, Jprobes, Return Probes
+  1. Concepts: Kprobes, Jprobes, Return Probes
+  2. Architectures Supported
+  3. Configuring Kprobes
+  4. API Reference
+  5. Kprobes Features and Limitations
+  6. Probe Overhead
+  7. TODO
+  8. Kprobes Example
+  9. Jprobes Example
+  10. Kretprobes Example
+  Appendix A: The kprobes debugfs interface
+  Appendix B: The kprobes sysctl interface
+
+Concepts: Kprobes, Jprobes, Return Probes
+=
 
 Kprobes enables you to dynamically break into any kernel routine and
 collect debugging and performance information non-disruptively. You
-can trap at almost any kernel code address(*), specifying a handler
+can trap at almost any kernel code address [1]_, specifying a handler
 routine to be invoked when the breakpoint is hit.
-(*: some parts of the kernel code can not be trapped, see 1.5 Blacklist)
+
+.. [1] some parts of the kernel code can not be trapped, see
+   :ref:`kprobes_blacklist`)
 
 There are currently three types of probes: kprobes, jprobes, and
 kretprobes (also called return probes).  A kprobe can be inserted
@@ -40,8 +46,8 @@ registration function such as register_kprobe() specifies 
where
 the probe is to be inserted and what handler is to be called when
 the probe is hit.
 
-There are also register_/unregister_*probes() functions for batch
-registration/unregistration of a group of *probes. These functions
+There are also ``register_/unregister_*probes()`` functions for batch
+registration/unregistration of a group of ``*probes``. These functions
 can speed up unregistration process when you have to unregister
 a lot of probes at once.
 
@@ -53,7 +59,8 @@ a post_handler, and how to use the maxactive and nmissed 
fields of
 a kretprobe.  But if you're in a hurry to start using Kprobes, you
 can skip ahead to section 2.
 
-1.1 How Does a Kprobe Work?
+How Does a Kprobe Work?
+---
 
 When a kprobe is registered, Kprobes makes a copy of the probed
 instruction and replaces the first byte(s) of the probed instruction
@@ -75,7 +82,8 @@ After the instruction is single-stepped, Kprobes executes the
 "post_handler," if any, that is associated with the kprobe.
 Execution then continues with the instruction following the probepoint.
 
-1.2 How Does a Jprobe Work?
+How Does a Jprobe Work?
+---
 
 A jprobe is implemented using a kprobe that is placed on a function's
 entry point.  It employs a simple mirroring principle to allow
@@ -113,9 +121,11 @@ more than eight function arguments, an argument of more 
than sixteen
 bytes, or more than 64 bytes of argument data, depending on
 architecture).
 
-1.3 Return Probes
+Return Probes
+-
 
-1.3.1 How Does a Return Probe Work?
+How Does a Return Probe Work?
+^
 
 When you call register_kretprobe(), Kprobes establishes a kprobe at
 the entry to the function.  When the probed function is called and this
@@ -150,7 +160,8 @@ zero when the return probe is registered, and is 
incremented every
 time the probed function is entered but there is no kretprobe_instance
 object available for establishing the return probe.
 
-1.3.2 Kretprobe entry-handler
+Kretprobe entry-handler
+^^^
 
 Kretprobes also provides an optional user-specified handler which 

[PATCH 27/30] parport-lowlevel.txt: standardize document format

[Mauro Carvalho Chehab]

Each text file under Documentation follows a different
format. This one uses a man-page like approach.

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

- Mark titles;
- Mark literals and literal blocks;
- Adjust identation.

Still, the best would be to move its contents to kernel-docs.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/parport-lowlevel.txt | 1303 +++-
 1 file changed, 832 insertions(+), 471 deletions(-)

diff --git a/Documentation/parport-lowlevel.txt 
b/Documentation/parport-lowlevel.txt
index 120eb20dbb09..0633d70ffda7 100644
--- a/Documentation/parport-lowlevel.txt
+++ b/Documentation/parport-lowlevel.txt
@@ -1,11 +1,12 @@
+===
 PARPORT interface documentation

+===
 
-Time-stamp: <2000-02-24 13:30:20 twaugh>
+:Time-stamp: <2000-02-24 13:30:20 twaugh>
 
 Described here are the following functions:
 
-Global functions:
+Global functions::
   parport_register_driver
   parport_unregister_driver
   parport_enumerate
@@ -31,7 +32,8 @@ Global functions:
   parport_set_timeout
 
 Port functions (can be overridden by low-level drivers):
-  SPP:
+
+  SPP::
 port->ops->read_data
 port->ops->write_data
 port->ops->read_status
@@ -43,23 +45,23 @@ Port functions (can be overridden by low-level drivers):
 port->ops->data_forward
 port->ops->data_reverse
 
-  EPP:
+  EPP::
 port->ops->epp_write_data
 port->ops->epp_read_data
 port->ops->epp_write_addr
 port->ops->epp_read_addr
 
-  ECP:
+  ECP::
 port->ops->ecp_write_data
 port->ops->ecp_read_data
 port->ops->ecp_write_addr
 
-  Other:
+  Other::
 port->ops->nibble_read_data
 port->ops->byte_read_data
 port->ops->compat_write_data
 
-The parport subsystem comprises 'parport' (the core port-sharing
+The parport subsystem comprises ``parport`` (the core port-sharing
 code), and a variety of low-level drivers that actually do the port
 accesses.  Each low-level driver handles a particular style of port
 (PC, Amiga, and so on).
@@ -70,14 +72,14 @@ into global functions and port functions.
 The global functions are mostly for communicating between the device
 driver and the parport subsystem: acquiring a list of available ports,
 claiming a port for exclusive use, and so on.  They also include
-'generic' functions for doing standard things that will work on any
+``generic`` functions for doing standard things that will work on any
 IEEE 1284-capable architecture.
 
 The port functions are provided by the low-level drivers, although the
-core parport module provides generic 'defaults' for some routines.
+core parport module provides generic ``defaults`` for some routines.
 The port functions can be split into three groups: SPP, EPP, and ECP.
 
-SPP (Standard Parallel Port) functions modify so-called 'SPP'
+SPP (Standard Parallel Port) functions modify so-called ``SPP``
 registers: data, status, and control.  The hardware may not actually
 have registers exactly like that, but the PC does and this interface is
 modelled after common PC implementations.  Other low-level drivers may
@@ -95,58 +97,63 @@ to cope with peripherals that only tenuously support IEEE 
1284, a
 low-level driver specific function is provided, for altering 'fudge
 factors'.
 
-GLOBAL FUNCTIONS
-
+Global functions
+
 
 parport_register_driver - register a device driver with parport

+---
 
 SYNOPSIS
+
 
-#include 
+::
 
-struct parport_driver {
-   const char *name;
-   void (*attach) (struct parport *);
-   void (*detach) (struct parport *);
-   struct parport_driver *next;
-};
-int parport_register_driver (struct parport_driver *driver);
+   #include 
+
+   struct parport_driver {
+   const char *name;
+   void (*attach) (struct parport *);
+   void (*detach) (struct parport *);
+   struct parport_driver *next;
+   };
+   int parport_register_driver (struct parport_driver *driver);
 
 DESCRIPTION
+^^^
 
 In order to be notified about parallel ports when they are detected,
 parport_register_driver should be called.  Your driver will
 immediately be notified of all ports that have already been detected,
 and of each new port as low-level drivers are loaded.
 
-A 'struct parport_driver' contains the textual name of your driver,
+A ``struct parport_driver`` contains the textual name of your driver,
 a pointer to a function to handle new ports, and a pointer to a
 function to handle ports going away due to a low-level driver
 unloading.  Ports will only be detached if they are not being used
 (i.e. there are no devices registered on them).
 
-The visible parts of the 'struct parport *' argument given to

[PATCH 15/30] lockup-watchdogs.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 file is almost at ReST format. Just one title needs
to be adjusted, in order to follow the standard.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/lockup-watchdogs.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/lockup-watchdogs.txt 
b/Documentation/lockup-watchdogs.txt
index c8b8378513d6..290840c160af 100644
--- a/Documentation/lockup-watchdogs.txt
+++ b/Documentation/lockup-watchdogs.txt
@@ -30,7 +30,8 @@ timeout is set through the confusingly named "kernel.panic" 
sysctl),
 to cause the system to reboot automatically after a specified amount
 of time.
 
-=== Implementation ===
+Implementation
+==
 
 The soft and hard lockup detectors are built on top of the hrtimer and
 perf subsystems, respectively. A direct consequence of this is that,
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 24/30] ntb.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 file is using some other markup notation (likely, markdown).
Convert it to the adopted standard:

  - Adjust the header level markup;
  - Adjust identation for debugfs files and module parameters.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ntb.txt | 55 ++-
 1 file changed, 37 insertions(+), 18 deletions(-)

diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index 1d9bbabb6c79..e4771e5c2ad7 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -1,4 +1,6 @@
-# NTB Drivers
+===
+NTB Drivers
+===
 
 NTB (Non-Transparent Bridge) is a type of PCI-Express bridge chip that connects
 the separate memory systems of two computers to the same PCI-Express fabric.
@@ -10,7 +12,8 @@ fixed address.  Doorbell registers provide a way for peers to 
send interrupt
 events.  Memory windows allow translated read and write access to the peer
 memory.
 
-## NTB Core Driver (ntb)
+NTB Core Driver (ntb)
+=
 
 The NTB core driver defines an api wrapping the common feature set, and allows
 clients interested in NTB features to discover NTB the devices supported by
@@ -18,7 +21,8 @@ hardware drivers.  The term "client" is used here to mean an 
upper layer
 component making use of the NTB api.  The term "driver," or "hardware driver,"
 is used here to mean a driver for a specific vendor and model of NTB hardware.
 
-## NTB Client Drivers
+NTB Client Drivers
+==
 
 NTB client drivers should register with the NTB core driver.  After
 registering, the client probe and remove functions will be called appropriately
@@ -26,7 +30,8 @@ as ntb hardware, or hardware drivers, are inserted and 
removed.  The
 registration uses the Linux Device framework, so it should feel familiar to
 anyone who has written a pci driver.
 
-### NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev)
+NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev)
+--
 
 The primary client for NTB is the Transport client, used in tandem with NTB
 Netdev.  These drivers function together to create a logical link to the peer,
@@ -37,7 +42,8 @@ Transport queue pair.  Network data is copied between socket 
buffers and the
 Transport queue pair buffer.  The Transport client may be used for other things
 besides Netdev, however no other applications have yet been written.
 
-### NTB Ping Pong Test Client (ntb\_pingpong)
+NTB Ping Pong Test Client (ntb\_pingpong)
+-
 
 The Ping Pong test client serves as a demonstration to exercise the doorbell
 and scratchpad registers of NTB hardware, and as an example simple NTB client.
@@ -64,7 +70,8 @@ Module Parameters:
 * dyndbg - It is suggested to specify dyndbg=+p when loading this module, and
then to observe debugging output on the console.
 
-### NTB Tool Test Client (ntb\_tool)
+NTB Tool Test Client (ntb\_tool)
+
 
 The Tool test client serves for debugging, primarily, ntb hardware and drivers.
 The Tool provides access through debugfs for reading, setting, and clearing the
@@ -74,48 +81,60 @@ The Tool does not currently have any module parameters.
 
 Debugfs Files:
 
-* *debugfs*/ntb\_tool/*hw*/ - A directory in debugfs will be created for each
+* *debugfs*/ntb\_tool/*hw*/
+   A directory in debugfs will be created for each
NTB device probed by the tool.  This directory is shortened to *hw*
below.
-* *hw*/db - This file is used to read, set, and clear the local doorbell.  Not
+* *hw*/db
+   This file is used to read, set, and clear the local doorbell.  Not
all operations may be supported by all hardware.  To read the doorbell,
read the file.  To set the doorbell, write `s` followed by the bits to
set (eg: `echo 's 0x0101' > db`).  To clear the doorbell, write `c`
followed by the bits to clear.
-* *hw*/mask - This file is used to read, set, and clear the local doorbell 
mask.
+* *hw*/mask
+   This file is used to read, set, and clear the local doorbell mask.
See *db* for details.
-* *hw*/peer\_db - This file is used to read, set, and clear the peer doorbell.
+* *hw*/peer\_db
+   This file is used to read, set, and clear the peer doorbell.
See *db* for details.
-* *hw*/peer\_mask - This file is used to read, set, and clear the peer doorbell
+* *hw*/peer\_mask
+   This file is used to read, set, and clear the peer doorbell
mask.  See *db* for details.
-* *hw*/spad - This file is used to read and write local scratchpads.  To read
+* *hw*/spad
+   This file is used to read and write local scratchpads.  To read

[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 
---
 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.billa...@gmail.com or as advertised on Xillybus' site.
 
-Author: Eli Billauer, Xillybus Ltd. (http://xillybus.com)
-Email:  eli.billa...@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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 29/30] phy.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;
- use :Author: for authorship;
- mark literal blocks.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/phy.txt | 106 +++---
 1 file changed, 67 insertions(+), 39 deletions(-)

diff --git a/Documentation/phy.txt b/Documentation/phy.txt
index 383cdd863f08..457c3e0f86d6 100644
--- a/Documentation/phy.txt
+++ b/Documentation/phy.txt
@@ -1,10 +1,14 @@
-   PHY SUBSYSTEM
- Kishon Vijay Abraham I 
+=
+PHY subsystem
+=
+
+:Author: Kishon Vijay Abraham I 
 
 This document explains the Generic PHY Framework along with the APIs provided,
 and how-to-use.
 
-1. Introduction
+Introduction
+
 
 *PHY* is the abbreviation for physical layer. It is used to connect a device
 to the physical medium e.g., the USB controller has a PHY to provide functions
@@ -21,7 +25,8 @@ better code maintainability.
 This framework will be of use only to devices that use external PHY (PHY
 functionality is not embedded within the controller).
 
-2. Registering/Unregistering the PHY provider
+Registering/Unregistering the PHY provider
+==
 
 PHY provider refers to an entity that implements one or more PHY instances.
 For the simple case where the PHY provider implements only a single instance of
@@ -30,11 +35,14 @@ of_phy_simple_xlate. If the PHY provider implements 
multiple instances, it
 should provide its own implementation of of_xlate. of_xlate is used only for
 dt boot case.
 
-#define of_phy_provider_register(dev, xlate)\
-__of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
+::
 
-#define devm_of_phy_provider_register(dev, xlate)   \
-__devm_of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
+   #define of_phy_provider_register(dev, xlate)\
+   __of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
+
+   #define devm_of_phy_provider_register(dev, xlate)   \
+   __devm_of_phy_provider_register((dev), NULL, THIS_MODULE,
+   (xlate))
 
 of_phy_provider_register and devm_of_phy_provider_register macros can be used 
to
 register the phy_provider and it takes device and of_xlate as
@@ -47,28 +55,35 @@ nodes within extra levels for context and extensibility, in 
which case the low
 level of_phy_provider_register_full() and devm_of_phy_provider_register_full()
 macros can be used to override the node containing the children.
 
-#define of_phy_provider_register_full(dev, children, xlate) \
-   __of_phy_provider_register(dev, children, THIS_MODULE, xlate)
+::
 
-#define devm_of_phy_provider_register_full(dev, children, xlate) \
-   __devm_of_phy_provider_register_full(dev, children, THIS_MODULE, xlate)
+   #define of_phy_provider_register_full(dev, children, xlate) \
+   __of_phy_provider_register(dev, children, THIS_MODULE, xlate)
 
-void devm_of_phy_provider_unregister(struct device *dev,
-   struct phy_provider *phy_provider);
-void of_phy_provider_unregister(struct phy_provider *phy_provider);
+   #define devm_of_phy_provider_register_full(dev, children, xlate) \
+   __devm_of_phy_provider_register_full(dev, children,
+THIS_MODULE, xlate)
+
+   void devm_of_phy_provider_unregister(struct device *dev,
+   struct phy_provider *phy_provider);
+   void of_phy_provider_unregister(struct phy_provider *phy_provider);
 
 devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to
 unregister the PHY.
 
-3. Creating the PHY
+Creating the PHY
+
 
 The PHY driver should create the PHY in order for other peripheral controllers
 to make use of it. The PHY framework provides 2 APIs to create the PHY.
 
-struct phy *phy_create(struct device *dev, struct device_node *node,
-  const struct phy_ops *ops);
-struct phy *devm_phy_create(struct device *dev, struct device_node *node,
-   const struct phy_ops *ops);
+::
+
+   struct phy *phy_create(struct device *dev, struct device_node *node,
+  const struct phy_ops *ops);
+   struct phy *devm_phy_create(struct device *dev,
+   struct device_node *node,
+   const struct phy_ops *ops);
 
 The PHY drivers can use one of the above 2 APIs to create the PHY by passing
 the device pointer and phy ops.
@@ -84,12 +99,16 @@ phy_ops to get back the private data.
 Before the controller can make use of the PHY, it has to get a reference to
 it. This framework provides 

[PATCH 16/30] lzo.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 markups for section titles;
- mark literal blocks;
- use ".. important::" for an important note.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/lzo.txt | 27 +--
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/Documentation/lzo.txt b/Documentation/lzo.txt
index 285c54f66779..6fa6a93d0949 100644
--- a/Documentation/lzo.txt
+++ b/Documentation/lzo.txt
@@ -1,8 +1,9 @@
-
+===
 LZO stream format as understood by Linux's LZO decompressor
 ===
 
 Introduction
+
 
   This is not a specification. No specification seems to be publicly available
   for the LZO stream format. This document describes what input format the LZO
@@ -14,12 +15,13 @@ Introduction
   for future bug reports.
 
 Description
+===
 
   The stream is composed of a series of instructions, operands, and data. The
   instructions consist in a few bits representing an opcode, and bits forming
   the operands for the instruction, whose size and position depend on the
   opcode and on the number of literals copied by previous instruction. The
-  operands are used to indicate :
+  operands are used to indicate:
 
 - a distance when copying data from the dictionary (past output buffer)
 - a length (number of bytes to copy from dictionary)
@@ -38,7 +40,7 @@ Description
   of bits in the operand. If the number of bits isn't enough to represent the
   length, up to 255 may be added in increments by consuming more bytes with a
   rate of at most 255 per extra byte (thus the compression ratio cannot exceed
-  around 255:1). The variable length encoding using #bits is always the same :
+  around 255:1). The variable length encoding using #bits is always the same::
 
length = byte & ((1 << #bits) - 1)
if (!length) {
@@ -67,15 +69,19 @@ Description
   instruction may encode this distance (0001HLLL), it takes one LE16 operand
   for the distance, thus requiring 3 bytes.
 
-  IMPORTANT NOTE : in the code some length checks are missing because certain
-  instructions are called under the assumption that a certain number of bytes
-  follow because it has already been guaranteed before parsing the 
instructions.
-  They just have to "refill" this credit if they consume extra bytes. This is
-  an implementation design choice independent on the algorithm or encoding.
+  .. important::
+
+ In the code some length checks are missing because certain instructions
+ are called under the assumption that a certain number of bytes follow
+ because it has already been guaranteed before parsing the instructions.
+ They just have to "refill" this credit if they consume extra bytes. This
+ is an implementation design choice independent on the algorithm or
+ encoding.
 
 Byte sequences
+==
 
-  First byte encoding :
+  First byte encoding::
 
   0..17   : follow regular instruction encoding, see below. It is worth
 noting that codes 16 and 17 will represent a block copy from
@@ -91,7 +97,7 @@ Byte sequences
 state = 4 [ don't copy extra literals ]
 skip byte
 
-  Instruction encoding :
+  Instruction encoding::
 
   0 0 0 0 X X X X  (0..15)
 Depends on the number of literals copied by the last instruction.
@@ -156,6 +162,7 @@ Byte sequences
distance = (H << 3) + D + 1
 
 Authors
+===
 
   This document was written by Willy Tarreau  on 2014/07/19 
during an
   analysis of the decompression code available in Linux 3.16-rc5. The code is
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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 
-=
+=
+
+
+:Date: January 18, 2007
+:Author: Rob Landley 
 
 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(, "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(); 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 = 

[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 
---
 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 
- Last Updated: 28 Aug 2002
+===
+Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe
+===
 
+:Author: Robert Love 
+: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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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...@intel.com
+:Author: 2006 luming...@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/pci:00/:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- DVI0
-|   |-- device -> ../../../devices/pci:00/:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- LCD0
-|   |-- device -> ../../../devices/pci:00/:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-`-- TV0
-   |-- device -> ../../../devices/pci:00/: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/pci:00/:00:01.0
+   |   |-- state
+   |   |-- subsystem -> ../../../class/video_output
+   |   `-- uevent
+   |-- DVI0
+   |   |-- device -> ../../../devices/pci:00/:00:01.0
+   |   |-- state
+   |   |-- subsystem -> ../../../class/video_output
+   |   `-- uevent
+   |-- LCD0
+   |   |-- device -> ../../../devices/pci:00/:00:01.0
+   |   |-- state
+   |   |-- subsystem -> ../../../class/video_output
+   |   `-- uevent
+   `-- TV0
+  |-- device -> ../../../devices/pci:00/:00:01.0
+  |-- state
+  |-- subsystem -> ../../../class/video_output
+  `-- uevent
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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
+ ==
+dateRTC-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
+nameThe name of the RTC corresponding to this sysfs directory
+since_epoch The number of seconds since the epoch according to the RTC
+timeRTC-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

--
To unsubscribe from this 

[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 
---
 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 
-
+
 The robust futex ABI
-
+
+
+:Author: Started by Paul Jackson 
+
 
 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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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 ,
+:Author: Johannes Berg 
+
+: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  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 

[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 
---
 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 
+===
+SipHash - a short input PRF
+===
+
+:Author: Written by Jason A. Donenfeld 
 
 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(, 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(, sizeof(key));
 
-void init_hashtable(struct some_hashtable *table)
-{
-   get_random_bytes(>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 >hashtable[siphash(input, sizeof(*input), >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(>key, sizeof(table->key));
+   }
+
+   static inline hlist_head *some_hashtable_bucket(struct some_hashtable 
*table, struct interesting_input *input)
+   {
+   return >hashtable[siphash(input, sizeof(*input), 
>key) & (HASH_SIZE(table->hashtable) - 1)];
+   }
 
 You may then iterate like usual over the returned 

[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 
---
 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()
 
@@ -153,11 +159,15 @@ Therefore the use of x or  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 = 
 
  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 = 
 
@@ -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);

[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 
---
 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 
+
+A description of what robust futexes are
+
+
+:Started by: Ingo Molnar 
 
 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_DIED0x4000
 
@@ -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   0x8000
 
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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
-, 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
+, 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
-.
+For userspace, XZ Utils provide a zlib-like compression library
+and a gzip-like command line tool. XZ Utils can be downloaded from
+.
 
 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 

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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 
-last updated: Oct. 16, 2002

+=
 
+:Author: Adam Belay 
+: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  " > resources
- - the configuration number
- - static or dynamic
-   static = for next boot
-   dynamic = now
+::
 
--disabling a device
+   # echo "manual  " > resources
 
-#echo "disable" > resources
+- the configuration number
+- 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 

[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 
---
 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
- 
+:Author: Gustavo Padovan 
 
 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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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, 
-
+.. include:: 
 
-1. Intro
-
-   This small document describes the "Video Mode Selection" feature which
+=
+Video Mode Selection Support 2.13
+=
+
+:Copyright: |copy| 1995--1999 Martin Mares, 
+
+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  to see video modes available, 
 to continue or wait 30 secs" message. If you press , you enter the
 menu, if you press  or wait 30 seconds, the kernel will boot up in
 the standard 80x25 mode.
 
-   The menu looks like:
+The menu looks like::
 
-Video adapter: 
-Mode:COLSxROWS:
-0  0F00  80x25
-1  0F01  80x50
-2  0F02  80x43
-3  0F03  80x26
-
-Enter mode number or `scan': 
+   Video adapter: 
+   Mode:COLSxROWS:
+   0  0F00  80x25
+   1  0F01  80x50
+   2  0F02  80x43
+   3  0F03  80x26
+   
+   Enter mode number or ``scan``: 
 
-tells what video adapter did Linux detect
+ 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).
 
-encourages you to enter the item number or mode ID
+ encourages you to enter the item number or mode ID
 you wish to set and press . 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  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 

[PATCH 18/30] memory-barriers.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 (#) instead of (*) as the latter is not recognized.
  As a bonus, using (#) will make it to auto-number paragraphs
  on PDF/LaTeX and HTML outputs;
- use the ReST markup for auto-numbered footnotes;
- comment the internal CONTENTS table;
- use "::" instead of ":" in order to mark literal blocks and
  ascii artwork;
- use the ReST markups for a table;
- use "-" for some bulleted lists that aren't marked;
- Use :Author: for authorship;
- Don't use capital leters on titles.

NOTE:

Trying to build this file with Sphinx will produce
some warnings:
Documentation/memory-barriers.rst:192: WARNING: Inline emphasis 
start-string without end-string.

That's because, on several places, it use asterisks like "*Q"
to identify variables.

As asterisks are used for emphasis, it expects an end
asterisk to put everything between them in italics.

In order to avoid it, either one of the notation below
is needed:
- \*Q
- "*Q"
- ``*Q``

The first notation can be confusing for the ones reading the
file in its ascii format. So, I don't think it is a good
idea to use it.

The other two notations would be OK. ``*Q`` gives the
additional bonus of using a different font for html/pdf
output.

For now, as we're just standardizing the document
notation, let's not touch it, but we should later
revisit this, when moving this file to one of the Kernel
books.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/memory-barriers.txt | 660 +++---
 1 file changed, 329 insertions(+), 331 deletions(-)

diff --git a/Documentation/memory-barriers.txt 
b/Documentation/memory-barriers.txt
index 732f10ea382e..f37b418b3022 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -1,14 +1,13 @@
-
-LINUX KERNEL MEMORY BARRIERS
-
+
+Linux kernel memory barriers
+
 
-By: David Howells 
-Paul E. McKenney 
-Will Deacon 
-Peter Zijlstra 
+:Author: David Howells 
+:Author: Paul E. McKenney 
+:Author: Will Deacon 
+:Author: Peter Zijlstra 
 
-==
-DISCLAIMER
+Disclaimer
 ==
 
 This document is not a specification; it is intentionally (for the sake of
@@ -35,16 +34,14 @@ architecture because the way that arch works renders an 
explicit barrier
 unnecessary in that case.
 
 
-
-CONTENTS
-
+.. CONTENTS
 
- (*) Abstract memory access model.
+ (#) Abstract memory access model.
 
  - Device operations.
  - Guarantees.
 
- (*) What are memory barriers?
+ (#) What are memory barriers?
 
  - Varieties of memory barrier.
  - What may not be assumed about memory barriers?
@@ -55,58 +52,57 @@ CONTENTS
  - Read memory barriers vs load speculation.
  - Transitivity
 
- (*) Explicit kernel barriers.
+ (#) Explicit kernel barriers.
 
  - Compiler barrier.
  - CPU memory barriers.
  - MMIO write barrier.
 
- (*) Implicit kernel memory barriers.
+ (#) Implicit kernel memory barriers.
 
  - Lock acquisition functions.
  - Interrupt disabling functions.
  - Sleep and wake-up functions.
  - Miscellaneous functions.
 
- (*) Inter-CPU acquiring barrier effects.
+ (#) Inter-CPU acquiring barrier effects.
 
  - Acquires vs memory accesses.
  - Acquires vs I/O accesses.
 
- (*) Where are memory barriers needed?
+ (#) Where are memory barriers needed?
 
  - Interprocessor interaction.
  - Atomic operations.
  - Accessing devices.
  - Interrupts.
 
- (*) Kernel I/O barrier effects.
+ (#) Kernel I/O barrier effects.
 
- (*) Assumed minimum execution ordering model.
+ (#) Assumed minimum execution ordering model.
 
- (*) The effects of the cpu cache.
+ (#) The effects of the cpu cache.
 
  - Cache coherency.
  - Cache coherency vs DMA.
  - Cache coherency vs MMIO.
 
- (*) The things CPUs get up to.
+ (#) The things CPUs get up to.
 
  - And then there's the Alpha.
  - Virtual Machine Guests.
 
- (*) Example uses.
+ (#) Example uses.
 
  - Circular buffers.
 
- (*) References.
+ (#) References.
 
 
-
-ABSTRACT MEMORY ACCESS MODEL
+Abstract memory access model
 
 
-Consider the following abstract model of the system:
+Consider the following abstract model of the system::
 
::
::
@@ -143,7 +139,7 @@ CPU are 

[PATCH 28/30] percpu-rw-semaphore.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 already adopting the standard format,
with a single exception: we're using this convention
for the document title:
===
foo
===

So, adjust the title of this document to follow the
standard.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/percpu-rw-semaphore.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/percpu-rw-semaphore.txt 
b/Documentation/percpu-rw-semaphore.txt
index 7d3c82431909..247de6410855 100644
--- a/Documentation/percpu-rw-semaphore.txt
+++ b/Documentation/percpu-rw-semaphore.txt
@@ -1,5 +1,6 @@
+
 Percpu rw semaphores
-
+
 
 Percpu rw semaphores is a new read-write semaphore design that is
 optimized for locking for reading.
-- 
2.9.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[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 
---
 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 ?S00: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 

[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 
---
 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 
+Typical usage
+=
 
-/* in case we were given a valid 'rproc' handle */
-int dummy_rproc_example(struct rproc *my_rproc)
-{
+::
+
+  #include 
+
+  /* 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,
 

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

[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 
---
 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 
- * Kirti Wankhede 
- *
- * 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:: 
+
+=
+VFIO Mediated devices
+=
+
+:Copyright: |copy| 2016, NVIDIA CORPORATION. All rights reserved.
+:Author: Neo Jia 
+:Author: Kirti Wankhede 
+
+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]
-| |--- []
-| |   |--- create
-| |   |--- name
-| |   |--- available_instances
-| |   |--- device_api
-| |   |--- description
-| |   |--- [devices]
-| |--- []
-| |   |--- create
-| |   |--- name
-| |   |--- available_instances
-| |   |--- device_api
-| |   |--- description
-| |   |--- [devices]
-| |--- []
-|  |--- create
-|  |--- name
-|  

[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 
---
 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 :06:0d.0
+Assume user wants to access PCI device :06:0d.0::
 
-$ readlink /sys/bus/pci/devices/:06:0d.0/iommu_group
-../../../../kernel/iommu_groups/26
+   $ readlink /sys/bus/pci/devices/: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 :06:0d.0
-06:0d.0 0401: 1102:0002 (rev 08)
-# echo :06:0d.0 > /sys/bus/pci/devices/:06:0d.0/driver/unbind
-# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
+   $ lspci -n -s :06:0d.0
+   06:0d.0 0401: 1102:0002 (rev 08)
+   # echo :06:0d.0 > /sys/bus/pci/devices/: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/:06:0d.0/iommu_group/devices
-total 0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :00:1e.0 ->
-   ../../../../devices/pci:00/:00:1e.0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :06:0d.0 ->
-   ../../../../devices/pci:00/:00:1e.0/:06:0d.0
-lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :06:0d.1 ->
-   ../../../../devices/pci:00/:00:1e.0/:06:0d.1
+   $ ls -l /sys/bus/pci/devices/:06:0d.0/iommu_group/devices
+   total 0
+   lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :00:1e.0 ->
+   ../../../../devices/pci:00/:00:1e.0
+   lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :06:0d.0 ->
+   ../../../../devices/pci:00/:00:1e.0/:06:0d.0
+   lrwxrwxrwx. 1 root root 0 Apr 23 16:13 :06:0d.1 ->
+   ../../../../devices/pci:00/:00:1e.0/: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 :06:0d.1 to the group following the same
 procedure as above.  

[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 
---
 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 
-Last revised: September 5, 2003
+:Author: Written by Geert Uytterhoeven 
+: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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mauro Carvalho Chehab]

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

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

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Mauro Carvalho Chehab 
---
 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  > /sys/devices/platform/dell_rbu/packet_size
+be downloaded. It is done as below::
+
+   echo  > /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
 

[PATCH 27/31] intel_txt.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 main title one level;
- fix the bulleted list markup;
- use bulletted list markup where needed;
- add whitespaces where needed;
- mark literal blocks;
- remove extra ":" after section titles.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/intel_txt.txt | 63 -
 1 file changed, 40 insertions(+), 23 deletions(-)

diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.txt
index 91d89c540709..d83c1a2122c9 100644
--- a/Documentation/intel_txt.txt
+++ b/Documentation/intel_txt.txt
@@ -1,4 +1,5 @@
-Intel(R) TXT Overview:
+=
+Intel(R) TXT Overview
 =
 
 Intel's technology for safer computing, Intel(R) Trusted Execution
@@ -8,9 +9,10 @@ provide the building blocks for creating trusted platforms.
 Intel TXT was formerly known by the code name LaGrande Technology (LT).
 
 Intel TXT in Brief:
-o  Provides dynamic root of trust for measurement (DRTM)
-o  Data protection in case of improper shutdown
-o  Measurement and verification of launched environment
+
+-  Provides dynamic root of trust for measurement (DRTM)
+-  Data protection in case of improper shutdown
+-  Measurement and verification of launched environment
 
 Intel TXT is part of the vPro(TM) brand and is also available some
 non-vPro systems.  It is currently available on desktop systems
@@ -24,16 +26,21 @@ which has been updated for the new released platforms.
 
 Intel TXT has been presented at various events over the past few
 years, some of which are:
-  LinuxTAG 2008:
+
+  - LinuxTAG 2008:
   http://www.linuxtag.org/2008/en/conf/events/vp-donnerstag.html
-  TRUST2008:
+
+  - TRUST2008:
   http://www.trust-conference.eu/downloads/Keynote-Speakers/
   3_David-Grawrock_The-Front-Door-of-Trusted-Computing.pdf
-  IDF, Shanghai:
+
+  - IDF, Shanghai:
   http://www.prcidf.com.cn/index_en.html
-  IDFs 2006, 2007 (I'm not sure if/where they are online)
 
-Trusted Boot Project Overview:
+  - IDFs 2006, 2007
+ (I'm not sure if/where they are online)
+
+Trusted Boot Project Overview
 =
 
 Trusted Boot (tboot) is an open source, pre-kernel/VMM module that
@@ -87,11 +94,12 @@ Intel-provided firmware).
 How Does it Work?
 =
 
-o  Tboot is an executable that is launched by the bootloader as
+-  Tboot is an executable that is launched by the bootloader as
the "kernel" (the binary the bootloader executes).
-o  It performs all of the work necessary to determine if the
+-  It performs all of the work necessary to determine if the
platform supports Intel TXT and, if so, executes the GETSEC[SENTER]
processor instruction that initiates the dynamic root of trust.
+
-  If tboot determines that the system does not support Intel TXT
   or is not configured correctly (e.g. the SINIT AC Module was
   incorrect), it will directly launch the kernel with no changes
@@ -99,12 +107,14 @@ o  It performs all of the work necessary to determine if 
the
-  Tboot will output various information about its progress to the
   terminal, serial port, and/or an in-memory log; the output
   locations can be configured with a command line switch.
-o  The GETSEC[SENTER] instruction will return control to tboot and
+
+-  The GETSEC[SENTER] instruction will return control to tboot and
tboot then verifies certain aspects of the environment (e.g. TPM NV
lock, e820 table does not have invalid entries, etc.).
-o  It will wake the APs from the special sleep state the GETSEC[SENTER]
+-  It will wake the APs from the special sleep state the GETSEC[SENTER]
instruction had put them in and place them into a wait-for-SIPI
state.
+
-  Because the processors will not respond to an INIT or SIPI when
   in the TXT environment, it is necessary to create a small VT-x
   guest for the APs.  When they run in this guest, they will
@@ -112,8 +122,10 @@ o  It will wake the APs from the special sleep state the 
GETSEC[SENTER]
   VMEXITs, and then disable VT and jump to the SIPI vector.  This
   approach seemed like a better choice than having to insert
   special code into the kernel's MP wakeup sequence.
-o  Tboot then applies an (optional) user-defined launch policy to
+
+-  Tboot then applies an (optional) user-defined launch policy to
verify the kernel and initrd.
+
-  This policy is rooted in TPM NV and is described in the tboot
   project.  The tboot project also contains code for tools to
   create and provision the policy.
@@ -121,30 +133,34 @@ o  Tboot then applies an (optional) user-defined launch 
policy to
   then any kernel will be launched.
-  Policy action 

Re: [PATCH v5 17/32] x86/mm: Add support to access boot related data in the clear

[Matt Fleming]

On Mon, 15 May, at 08:35:17PM, Borislav Petkov wrote:
> On Tue, Apr 18, 2017 at 04:19:21PM -0500, Tom Lendacky wrote:
>
> > +   paddr = boot_params.efi_info.efi_memmap_hi;
> > +   paddr <<= 32;
> > +   paddr |= boot_params.efi_info.efi_memmap;
> > +   if (phys_addr == paddr)
> > +   return true;
> > +
> > +   paddr = boot_params.efi_info.efi_systab_hi;
> > +   paddr <<= 32;
> > +   paddr |= boot_params.efi_info.efi_systab;
> 
> So those two above look like could be two global vars which are
> initialized somewhere in the EFI init path:
> 
> efi_memmap_phys and efi_systab_phys or so.
> 
> Matt ?
> 
> And then you won't need to create that paddr each time on the fly. I
> mean, it's not a lot of instructions but still...
 
We should already have the physical memmap address available in
'efi.memmap.phys_map'.

And the physical address of the system table should be in
'efi_phys.systab'. See efi_init().
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] mm, oom: cgroup-aware OOM-killer

[Balbir Singh]

On Thu, 2017-05-18 at 20:20 +0100, Roman Gushchin wrote:
> On Fri, May 19, 2017 at 04:37:27AM +1000, Balbir Singh wrote:
> > On Fri, May 19, 2017 at 3:30 AM, Michal Hocko  wrote:
> > > On Thu 18-05-17 17:28:04, Roman Gushchin wrote:
> > > > Traditionally, the OOM killer is operating on a process level.
> > > > Under oom conditions, it finds a process with the highest oom score
> > > > and kills it.
> > > > 
> > > > This behavior doesn't suit well the system with many running
> > > > containers. There are two main issues:
> > > > 
> > > > 1) There is no fairness between containers. A small container with
> > > > a few large processes will be chosen over a large one with huge
> > > > number of small processes.
> > > > 
> > > > 2) Containers often do not expect that some random process inside
> > > > will be killed. So, in general, a much safer behavior is
> > > > to kill the whole cgroup. Traditionally, this was implemented
> > > > in userspace, but doing it in the kernel has some advantages,
> > > > especially in a case of a system-wide OOM.
> > > > 
> > > > To address these issues, cgroup-aware OOM killer is introduced.
> > > > Under OOM conditions, it looks for a memcg with highest oom score,
> > > > and kills all processes inside.
> > > > 
> > > > Memcg oom score is calculated as a size of active and inactive
> > > > anon LRU lists, unevictable LRU list and swap size.
> > > > 
> > > > For a cgroup-wide OOM, only cgroups belonging to the subtree of
> > > > the OOMing cgroup are considered.
> > > 
> > > While this might make sense for some workloads/setups it is not a
> > > generally acceptable policy IMHO. We have discussed that different OOM
> > > policies might be interesting few years back at LSFMM but there was no
> > > real consensus on how to do that. One possibility was to allow bpf like
> > > mechanisms. Could you explore that path?
> > 
> > I agree, I think it needs more thought. I wonder if the real issue is 
> > something
> > else. For example
> > 
> > 1. Did we overcommit a particular container too much?
> 
> Imagine, you have a machine with multiple containers,
> each with it's own process tree, and the machine is overcommited,
> i.e. sum of container's memory limits is larger the amount available RAM.
> 
> In a case of a system-wide OOM some random container will be affected.
> 

The random container containing the most expensive task, yes!

> Historically, this problem was solving by some user-space daemon,
> which was monitoring OOM events and cleaning up affected containers.
> But this approach can't solve the main problem: non-optimal selection
> of a victim. 

Why do you think the problem is non-optimal selection, is it because
we believe that memory cgroup limits should play a role in decision
making of global OOM?


> 
> > 2. Do we need something like 
> > https://urldefense.proofpoint.com/v2/url?u=https-3A__lwn.net_Articles_604212_=DwIBaQ=5VD0RTtNlTh3ycd41b3MUw=jJYgtDM7QT-W-Fz_d29HYQ=9jV4id5lmsjFJj1kQjJk0auyQ3bzL27-f6Ur6ZNw36c=ElsS25CoZSPba6ke7O-EIsR7lN0psP6tDVyLnGqCMfs=
> >   to solve
> > the problem?
>
 
The URL got changed to something non-parsable, probably for security, but
could you email client please not do that.

> I don't think it's related.

I was thinking that if we have virtual memory limits and we could set
some sane ones, we could avoid OOM altogether. OOM is a big hammer and
having allocations fail is far more acceptable than killing processes.
I believe that several applications may have much larger VM than actual
memory usage, but I believe with a good overcommit/virtual memory limiter
the problem can be better tackled.

> 
> > 3. We have oom notifiers now, could those be used (assuming you are 
> > interested
> > in non memcg related OOM's affecting a container
> 
> They can be used to inform an userspace daemon about an already happened OOM,
> but they do not affect victim selection.

Yes, the whole point is for the OS to select the victim, the notifiers
provide an opportunity for us to do reclaim to probably prevent OOM

In oom_kill, I see

blocking_notifier_call_chain(_notify_list, 0, );
if (freed > 0)
/* Got some memory back in the last second. */
return true;

Could the notification to user space then decide what to cleanup to free
memory? We also have event notification inside of memcg. I am trying to
understand why these are not sufficient?

We also have soft limits to push containers to a smaller size at the
time of global pressure.

> 
> > 4. How do we determine limits for these containers? From a fariness
> > perspective
> 
> Limits are usually set from some high-level understanding of the nature
> of tasks which are working inside, but overcommiting the machine is
> a common place, I assume.

Agreed overcommit is a given and that is why we wrote the cgroup controllers.
I was wondering if the container limits not being set correctly could cause
these 

Re: [RFC PATCH] mm, oom: cgroup-aware OOM-killer

[Johannes Weiner]

On Fri, May 19, 2017 at 04:37:27AM +1000, Balbir Singh wrote:
> On Fri, May 19, 2017 at 3:30 AM, Michal Hocko  wrote:
> > On Thu 18-05-17 17:28:04, Roman Gushchin wrote:
> >> Traditionally, the OOM killer is operating on a process level.
> >> Under oom conditions, it finds a process with the highest oom score
> >> and kills it.
> >>
> >> This behavior doesn't suit well the system with many running
> >> containers. There are two main issues:
> >>
> >> 1) There is no fairness between containers. A small container with
> >> a few large processes will be chosen over a large one with huge
> >> number of small processes.
> >>
> >> 2) Containers often do not expect that some random process inside
> >> will be killed. So, in general, a much safer behavior is
> >> to kill the whole cgroup. Traditionally, this was implemented
> >> in userspace, but doing it in the kernel has some advantages,
> >> especially in a case of a system-wide OOM.
> >>
> >> To address these issues, cgroup-aware OOM killer is introduced.
> >> Under OOM conditions, it looks for a memcg with highest oom score,
> >> and kills all processes inside.
> >>
> >> Memcg oom score is calculated as a size of active and inactive
> >> anon LRU lists, unevictable LRU list and swap size.
> >>
> >> For a cgroup-wide OOM, only cgroups belonging to the subtree of
> >> the OOMing cgroup are considered.
> >
> > While this might make sense for some workloads/setups it is not a
> > generally acceptable policy IMHO. We have discussed that different OOM
> > policies might be interesting few years back at LSFMM but there was no
> > real consensus on how to do that. One possibility was to allow bpf like
> > mechanisms. Could you explore that path?
> 
> I agree, I think it needs more thought. I wonder if the real issue is 
> something
> else. For example
> 
> 1. Did we overcommit a particular container too much?
> 2. Do we need something like https://lwn.net/Articles/604212/ to solve
> the problem?

The occasional OOM kill is an unavoidable reality on our systems (and
I bet on most deployments). If we tried not to overcommit, we'd waste
a *lot* of memory.

The problem is when OOM happens, we really want the biggest *job* to
get killed. Before cgroups, we assumed jobs were processes. But with
cgroups, the user is able to define a group of processes as a job, and
then an individual process is no longer a first-class memory consumer.

Without a patch like this, the OOM killer will compare the sizes of
the random subparticles that the jobs in the system are composed of
and kill the single biggest particle, leaving behind the incoherent
remains of one of the jobs. That doesn't make a whole lot of sense.

If you want to determine the most expensive car in a parking lot, you
can't go off and compare the price of one car's muffler with the door
handle of another, then point to a wind shield and yell "This is it!"

You need to compare the cars as a whole with each other.

> 3. We have oom notifiers now, could those be used (assuming you are interested
> in non memcg related OOM's affecting a container

Right now, we watch for OOM notifications and then have userspace kill
the rest of a job. That works - somewhat. What remains is the problem
that I described above, that comparing individual process sizes is not
meaningful when the terminal memory consumer is a cgroup.

> 4. How do we determine limits for these containers? From a fariness
> perspective

How do you mean?
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] mm, oom: cgroup-aware OOM-killer

[Roman Gushchin]

On Fri, May 19, 2017 at 04:37:27AM +1000, Balbir Singh wrote:
> On Fri, May 19, 2017 at 3:30 AM, Michal Hocko  wrote:
> > On Thu 18-05-17 17:28:04, Roman Gushchin wrote:
> >> Traditionally, the OOM killer is operating on a process level.
> >> Under oom conditions, it finds a process with the highest oom score
> >> and kills it.
> >>
> >> This behavior doesn't suit well the system with many running
> >> containers. There are two main issues:
> >>
> >> 1) There is no fairness between containers. A small container with
> >> a few large processes will be chosen over a large one with huge
> >> number of small processes.
> >>
> >> 2) Containers often do not expect that some random process inside
> >> will be killed. So, in general, a much safer behavior is
> >> to kill the whole cgroup. Traditionally, this was implemented
> >> in userspace, but doing it in the kernel has some advantages,
> >> especially in a case of a system-wide OOM.
> >>
> >> To address these issues, cgroup-aware OOM killer is introduced.
> >> Under OOM conditions, it looks for a memcg with highest oom score,
> >> and kills all processes inside.
> >>
> >> Memcg oom score is calculated as a size of active and inactive
> >> anon LRU lists, unevictable LRU list and swap size.
> >>
> >> For a cgroup-wide OOM, only cgroups belonging to the subtree of
> >> the OOMing cgroup are considered.
> >
> > While this might make sense for some workloads/setups it is not a
> > generally acceptable policy IMHO. We have discussed that different OOM
> > policies might be interesting few years back at LSFMM but there was no
> > real consensus on how to do that. One possibility was to allow bpf like
> > mechanisms. Could you explore that path?
> 
> I agree, I think it needs more thought. I wonder if the real issue is 
> something
> else. For example
> 
> 1. Did we overcommit a particular container too much?

Imagine, you have a machine with multiple containers,
each with it's own process tree, and the machine is overcommited,
i.e. sum of container's memory limits is larger the amount available RAM.

In a case of a system-wide OOM some random container will be affected.

Historically, this problem was solving by some user-space daemon,
which was monitoring OOM events and cleaning up affected containers.
But this approach can't solve the main problem: non-optimal selection
of a victim. 

> 2. Do we need something like 
> https://urldefense.proofpoint.com/v2/url?u=https-3A__lwn.net_Articles_604212_=DwIBaQ=5VD0RTtNlTh3ycd41b3MUw=jJYgtDM7QT-W-Fz_d29HYQ=9jV4id5lmsjFJj1kQjJk0auyQ3bzL27-f6Ur6ZNw36c=ElsS25CoZSPba6ke7O-EIsR7lN0psP6tDVyLnGqCMfs=
>   to solve
> the problem?

I don't think it's related.

> 3. We have oom notifiers now, could those be used (assuming you are interested
> in non memcg related OOM's affecting a container

They can be used to inform an userspace daemon about an already happened OOM,
but they do not affect victim selection.

> 4. How do we determine limits for these containers? From a fariness
> perspective

Limits are usually set from some high-level understanding of the nature
of tasks which are working inside, but overcommiting the machine is
a common place, I assume.

Thank you!

Roman
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] mm, oom: cgroup-aware OOM-killer

[Balbir Singh]

On Fri, May 19, 2017 at 3:30 AM, Michal Hocko  wrote:
> On Thu 18-05-17 17:28:04, Roman Gushchin wrote:
>> Traditionally, the OOM killer is operating on a process level.
>> Under oom conditions, it finds a process with the highest oom score
>> and kills it.
>>
>> This behavior doesn't suit well the system with many running
>> containers. There are two main issues:
>>
>> 1) There is no fairness between containers. A small container with
>> a few large processes will be chosen over a large one with huge
>> number of small processes.
>>
>> 2) Containers often do not expect that some random process inside
>> will be killed. So, in general, a much safer behavior is
>> to kill the whole cgroup. Traditionally, this was implemented
>> in userspace, but doing it in the kernel has some advantages,
>> especially in a case of a system-wide OOM.
>>
>> To address these issues, cgroup-aware OOM killer is introduced.
>> Under OOM conditions, it looks for a memcg with highest oom score,
>> and kills all processes inside.
>>
>> Memcg oom score is calculated as a size of active and inactive
>> anon LRU lists, unevictable LRU list and swap size.
>>
>> For a cgroup-wide OOM, only cgroups belonging to the subtree of
>> the OOMing cgroup are considered.
>
> While this might make sense for some workloads/setups it is not a
> generally acceptable policy IMHO. We have discussed that different OOM
> policies might be interesting few years back at LSFMM but there was no
> real consensus on how to do that. One possibility was to allow bpf like
> mechanisms. Could you explore that path?

I agree, I think it needs more thought. I wonder if the real issue is something
else. For example

1. Did we overcommit a particular container too much?
2. Do we need something like https://lwn.net/Articles/604212/ to solve
the problem?
3. We have oom notifiers now, could those be used (assuming you are interested
in non memcg related OOM's affecting a container
4. How do we determine limits for these containers? From a fariness
perspective

Just trying to understand what leads to the issues you are seeing

Balbir
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH] mm, oom: cgroup-aware OOM-killer

[Michal Hocko]

On Thu 18-05-17 17:28:04, Roman Gushchin wrote:
> Traditionally, the OOM killer is operating on a process level.
> Under oom conditions, it finds a process with the highest oom score
> and kills it.
> 
> This behavior doesn't suit well the system with many running
> containers. There are two main issues:
> 
> 1) There is no fairness between containers. A small container with
> a few large processes will be chosen over a large one with huge
> number of small processes.
> 
> 2) Containers often do not expect that some random process inside
> will be killed. So, in general, a much safer behavior is
> to kill the whole cgroup. Traditionally, this was implemented
> in userspace, but doing it in the kernel has some advantages,
> especially in a case of a system-wide OOM.
> 
> To address these issues, cgroup-aware OOM killer is introduced.
> Under OOM conditions, it looks for a memcg with highest oom score,
> and kills all processes inside.
> 
> Memcg oom score is calculated as a size of active and inactive
> anon LRU lists, unevictable LRU list and swap size.
> 
> For a cgroup-wide OOM, only cgroups belonging to the subtree of
> the OOMing cgroup are considered.

While this might make sense for some workloads/setups it is not a
generally acceptable policy IMHO. We have discussed that different OOM
policies might be interesting few years back at LSFMM but there was no
real consensus on how to do that. One possibility was to allow bpf like
mechanisms. Could you explore that path?
-- 
Michal Hocko
SUSE Labs
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v2 11/17] cgroup: Implement new thread mode semantics

[Waiman Long]

On 05/17/2017 05:47 PM, Tejun Heo wrote:
> Hello, Waiman.
>
> On Mon, May 15, 2017 at 09:34:10AM -0400, Waiman Long wrote:
>> The current thread mode semantics aren't sufficient to fully support
>> threaded controllers like cpu. The main problem is that when thread
>> mode is enabled at root (mainly for performance reason), all the
>> non-threaded controllers cannot be supported at all.
>>
>> To alleviate this problem, the roles of thread root and threaded
>> cgroups are now further separated. Now thread mode can only be enabled
>> on a non-root leaf cgroup whose parent will then become the thread
>> root. All the descendants of a threaded cgroup will still need to be
>> threaded. All the non-threaded resource will be accounted for in the
>> thread root. Unlike the previous thread mode, however, a thread root
>> can have non-threaded children where system resources like memory
>> can be further split down the hierarchy.
>>
>> Now we could have something like
>>
>>  R -- A -- B
>>   \
>>T1 -- T2
>>
>> where R is the thread root, A and B are non-threaded cgroups, T1 and
>> T2 are threaded cgroups. The cgroups R, T1, T2 form a threaded subtree
>> where all the non-threaded resources are accounted for in R.  The no
>> internal process constraint does not apply in the threaded subtree.
>> Non-threaded controllers need to properly handle the competition
>> between internal processes and child cgroups at the thread root.
>>
>> This model will be flexible enough to support the need of the threaded
>> controllers.
> I do like the approach and it does address the issue with requiring at
> least one level of nesting for the thread mode to be used with other
> controllers.  I need to think a bit more about it and mull over what
> Peterz was suggesting in the old thread.  I'll get back to you soon
> but I'd really prefer this and the earlier related patches to be in
> its own patchset so that we aren't dealing with different things at
> the same time.
>
> Thanks.
>
I have studied the email exchanges with your original thread mode
patchset. This patchset is aimed to hopefully address all the concerns
that Peterz has. This enhanced thread mode should address a big part of
the concern. However, I am not sure if this patch, by itself, is enough
to address all his concerns. That is why I also include 2 other major
changes in the next 2 patches. My goal is to move forward to allow all
controllers to be enabled for v2 eventually. We are not there yet, but I
hope this patchset can move thing forward meaningfully.

Regards,
Longman


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 31/32] x86: Add sysfs support for Secure Memory Encryption

[Borislav Petkov]

On Tue, Apr 18, 2017 at 04:22:12PM -0500, Tom Lendacky wrote:
> Add sysfs support for SME so that user-space utilities (kdump, etc.) can
> determine if SME is active.

But why do user-space tools need to know that?

I mean, when we load the kdump kernel, we do it with the first kernel,
with the kexec_load() syscall, AFAICT. And that code does a lot of
things during that init, like machine_kexec_prepare()->init_pgtable() to
prepare the ident mapping of the second kernel, for example.

What I'm aiming at is that the first kernel knows *exactly* whether SME
is enabled or not and doesn't need to tell the second one through some
sysfs entries - it can do that during loading.

So I don't think we need any userspace things at all...

Or?

-- 
Regards/Gruss,
Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/17] convert/reorganize Documentation/security/

[Kees Cook]

On Thu, May 18, 2017 at 9:49 AM, Jonathan Corbet  wrote:
> On Sat, 13 May 2017 04:51:36 -0700
> Kees Cook  wrote:
>
>> This ReSTifies everything under Documentation/security/, and reorganizes
>> some of it (mainly the LSMs) under /admin-guide/ per Jon's request. Since
>> /security/ is already being indexed under the kernel development portion
>> of the sphinx index, I didn't move it, keeping only things that were
>> directly related to internal kernel development (keys, creds, etc).
>>
>> I also updated some path references, and MAINTAINERS lines. Some of the
>> conversion could probably do with some tweaks, but I think this is a
>> good first step in the right direction.
>
> I agree with the need for tweaks :)  I fixed up key-request.rst a bit
> since I just couldn't stand it.
>
> Anyway, the set is applied, many thanks for doing this!

Awesome, thanks for the fixes!

-Kees

-- 
Kees Cook
Pixel Security
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation, kbuild: fix typo "minimun" -> "minimum"

[Jonathan Corbet]

On Thu, 18 May 2017 14:17:29 +0200
Tobias Klauser  wrote:

>  Documentation/kbuild/makefiles.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/kbuild/makefiles.txt 
> b/Documentation/kbuild/makefiles.txt
> index e18daca65ccd..659afd56ecdb 100644
> --- a/Documentation/kbuild/makefiles.txt
> +++ b/Documentation/kbuild/makefiles.txt
> @@ -1331,7 +1331,7 @@ See subsequent chapter for the syntax of the Kbuild 
> file.
>   --- 7.5 mandatory-y
>  
>   mandatory-y is essentially used by include/uapi/asm-generic/Kbuild.asm
> - to define the minimun set of headers that must be exported in
> + to define the minimum set of headers that must be exported in
>   include/asm.

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html