[PATCH v13 02/10] dt-bindings: document devicetree bindings for mux-controllers and gpio-mux

[Peter Rosin]

Allow specifying that a single multiplexer controller can be used to
control several parallel multiplexers, thus enabling sharing of the
multiplexer controller by different consumers.

Add a binding for a first mux controller in the form of a GPIO based mux
controller.

Acked-by: Jonathan Cameron 
Acked-by: Rob Herring 
Signed-off-by: Peter Rosin 
---
 Documentation/devicetree/bindings/mux/gpio-mux.txt |  69 +
 .../devicetree/bindings/mux/mux-controller.txt | 157 +
 MAINTAINERS|   6 +
 include/dt-bindings/mux/mux.h  |  16 +++
 4 files changed, 248 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mux/gpio-mux.txt
 create mode 100644 Documentation/devicetree/bindings/mux/mux-controller.txt
 create mode 100644 include/dt-bindings/mux/mux.h

diff --git a/Documentation/devicetree/bindings/mux/gpio-mux.txt 
b/Documentation/devicetree/bindings/mux/gpio-mux.txt
new file mode 100644
index ..b8f746344d80
--- /dev/null
+++ b/Documentation/devicetree/bindings/mux/gpio-mux.txt
@@ -0,0 +1,69 @@
+GPIO-based multiplexer controller bindings
+
+Define what GPIO pins are used to control a multiplexer. Or several
+multiplexers, if the same pins control more than one multiplexer.
+
+Required properties:
+- compatible : "gpio-mux"
+- mux-gpios : list of gpios used to control the multiplexer, least
+ significant bit first.
+- #mux-control-cells : <0>
+* Standard mux-controller bindings as decribed in mux-controller.txt
+
+Optional properties:
+- idle-state : if present, the state the mux will have when idle. The
+  special state MUX_IDLE_AS_IS is the default.
+
+The multiplexer state is defined as the number represented by the
+multiplexer GPIO pins, where the first pin is the least significant
+bit. An active pin is a binary 1, an inactive pin is a binary 0.
+
+Example:
+
+   mux: mux-controller {
+   compatible = "gpio-mux";
+   #mux-control-cells = <0>;
+
+   mux-gpios = < 0 GPIO_ACTIVE_HIGH>,
+   < 1 GPIO_ACTIVE_HIGH>;
+   };
+
+   adc-mux {
+   compatible = "io-channel-mux";
+   io-channels = < 0>;
+   io-channel-names = "parent";
+
+   mux-controls = <>;
+
+   channels = "sync-1", "in", "out", "sync-2";
+   };
+
+   i2c-mux {
+   compatible = "i2c-mux";
+   i2c-parent = <>;
+
+   mux-controls = <>;
+
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   i2c@0 {
+   reg = <0>;
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   ssd1307: oled@3c {
+   /* ... */
+   };
+   };
+
+   i2c@3 {
+   reg = <3>;
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   pca9555: pca9555@20 {
+   /* ... */
+   };
+   };
+   };
diff --git a/Documentation/devicetree/bindings/mux/mux-controller.txt 
b/Documentation/devicetree/bindings/mux/mux-controller.txt
new file mode 100644
index ..4f47e4bd2fa0
--- /dev/null
+++ b/Documentation/devicetree/bindings/mux/mux-controller.txt
@@ -0,0 +1,157 @@
+Common multiplexer controller bindings
+==
+
+A multiplexer (or mux) controller will have one, or several, consumer devices
+that uses the mux controller. Thus, a mux controller can possibly control
+several parallel multiplexers. Presumably there will be at least one
+multiplexer needed by each consumer, but a single mux controller can of course
+control several multiplexers for a single consumer.
+
+A mux controller provides a number of states to its consumers, and the state
+space is a simple zero-based enumeration. I.e. 0-1 for a 2-way multiplexer,
+0-7 for an 8-way multiplexer, etc.
+
+
+Consumers
+-
+
+Mux controller consumers should specify a list of mux controllers that they
+want to use with a property containing a 'mux-ctrl-list':
+
+   mux-ctrl-list ::=  [mux-ctrl-list]
+   single-mux-ctrl ::=  [mux-ctrl-specifier]
+   mux-ctrl-phandle : phandle to mux controller node
+   mux-ctrl-specifier : array of #mux-control-cells specifying the
+given mux controller (controller specific)
+
+Mux controller properties should be named "mux-controls". The exact meaning of
+each mux controller property must be documented in the device tree binding for
+each consumer. An optional property "mux-control-names" may contain a list of
+strings to label each of the mux controllers listed in the "mux-controls"
+property.
+
+Drivers for devices that use more than a 

[PATCH v13 03/10] mux: minimal mux subsystem and gpio-based mux controller

[Peter Rosin]

Add a new minimalistic subsystem that handles multiplexer controllers.
When multiplexers are used in various places in the kernel, and the
same multiplexer controller can be used for several independent things,
there should be one place to implement support for said multiplexer
controller.

A single multiplexer controller can also be used to control several
parallel multiplexers, that are in turn used by different subsystems
in the kernel, leading to a need to coordinate multiplexer accesses.
The multiplexer subsystem handles this coordination.

This new mux controller subsystem initially comes with a single backend
driver that controls gpio based multiplexers. Even though not needed by
this initial driver, the mux controller subsystem is prepared to handle
chips with multiple (independent) mux controllers.

Reviewed-by: Jonathan Cameron 
Signed-off-by: Peter Rosin 
---
 Documentation/driver-model/devres.txt |   8 +
 MAINTAINERS   |   2 +
 drivers/Kconfig   |   2 +
 drivers/Makefile  |   1 +
 drivers/mux/Kconfig   |  34 +++
 drivers/mux/Makefile  |   6 +
 drivers/mux/mux-core.c| 422 ++
 drivers/mux/mux-gpio.c| 114 +
 include/linux/mux.h   | 252 
 9 files changed, 841 insertions(+)
 create mode 100644 drivers/mux/Kconfig
 create mode 100644 drivers/mux/Makefile
 create mode 100644 drivers/mux/mux-core.c
 create mode 100644 drivers/mux/mux-gpio.c
 create mode 100644 include/linux/mux.h

diff --git a/Documentation/driver-model/devres.txt 
b/Documentation/driver-model/devres.txt
index efb8200819d6..e2343d9cbec7 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.txt
@@ -337,6 +337,14 @@ MEM
 MFD
   devm_mfd_add_devices()
 
+MUX
+  devm_mux_chip_alloc()
+  devm_mux_chip_free()
+  devm_mux_chip_register()
+  devm_mux_chip_unregister()
+  devm_mux_control_get()
+  devm_mux_control_put()
+
 PER-CPU MEM
   devm_alloc_percpu()
   devm_free_percpu()
diff --git a/MAINTAINERS b/MAINTAINERS
index 7fc06739c8ad..591eba737678 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8563,6 +8563,8 @@ M:Peter Rosin 
 S: Maintained
 F: Documentation/devicetree/bindings/mux/
 F: include/linux/dt-bindings/mux/
+F: include/linux/mux.h
+F: drivers/mux/
 
 MULTISOUND SOUND DRIVER
 M: Andrew Veliath 
diff --git a/drivers/Kconfig b/drivers/Kconfig
index 117ca14ccf85..a7ea13e1b869 100644
--- a/drivers/Kconfig
+++ b/drivers/Kconfig
@@ -204,4 +204,6 @@ source "drivers/fpga/Kconfig"
 
 source "drivers/fsi/Kconfig"
 
+source "drivers/mux/Kconfig"
+
 endmenu
diff --git a/drivers/Makefile b/drivers/Makefile
index 2eced9afba53..c0436f6dd5a9 100644
--- a/drivers/Makefile
+++ b/drivers/Makefile
@@ -177,3 +177,4 @@ obj-$(CONFIG_ANDROID)   += android/
 obj-$(CONFIG_NVMEM)+= nvmem/
 obj-$(CONFIG_FPGA) += fpga/
 obj-$(CONFIG_FSI)  += fsi/
+obj-$(CONFIG_MULTIPLEXER)  += mux/
diff --git a/drivers/mux/Kconfig b/drivers/mux/Kconfig
new file mode 100644
index ..41dfe08ead84
--- /dev/null
+++ b/drivers/mux/Kconfig
@@ -0,0 +1,34 @@
+#
+# Multiplexer devices
+#
+
+menuconfig MULTIPLEXER
+   tristate "Multiplexer subsystem"
+   help
+ Multiplexer controller subsystem. Multiplexers are used in a
+ variety of settings, and this subsystem abstracts their use
+ so that the rest of the kernel sees a common interface. When
+ multiple parallel multiplexers are controlled by one single
+ multiplexer controller, this subsystem also coordinates the
+ multiplexer accesses.
+
+ To compile the subsystem as a module, choose M here: the module will
+ be called mux-core.
+
+if MULTIPLEXER
+
+config MUX_GPIO
+   tristate "GPIO-controlled Multiplexer"
+   depends on OF && GPIOLIB
+   help
+ GPIO-controlled Multiplexer controller.
+
+ The driver builds a single multiplexer controller using a number
+ of gpio pins. For N pins, there will be 2^N possible multiplexer
+ states. The GPIO pins can be connected (by the hardware) to several
+ multiplexers, which in that case will be operated in parallel.
+
+ To compile the driver as a module, choose M here: the module will
+ be called mux-gpio.
+
+endif
diff --git a/drivers/mux/Makefile b/drivers/mux/Makefile
new file mode 100644
index ..bb16953f6290
--- /dev/null
+++ b/drivers/mux/Makefile
@@ -0,0 +1,6 @@
+#
+# Makefile for multiplexer devices.
+#
+
+obj-$(CONFIG_MULTIPLEXER)  += mux-core.o
+obj-$(CONFIG_MUX_GPIO) += mux-gpio.o
diff --git a/drivers/mux/mux-core.c b/drivers/mux/mux-core.c
new file mode 100644
index ..66a8bccfc3d7
--- /dev/null
+++ 

[PATCH v13 08/10] i2c: i2c-mux-gpmux: new driver

[Peter Rosin]

This is a general purpose i2c mux that uses a multiplexer controlled by
the multiplexer subsystem to do the muxing.

The user can select if the mux is to be mux-locked and parent-locked
as described in Documentation/i2c/i2c-topology.

Acked-by: Jonathan Cameron 
Acked-by: Wolfram Sang 
Signed-off-by: Peter Rosin 
---
 drivers/i2c/muxes/Kconfig |  13 +++
 drivers/i2c/muxes/Makefile|   1 +
 drivers/i2c/muxes/i2c-mux-gpmux.c | 173 ++
 3 files changed, 187 insertions(+)
 create mode 100644 drivers/i2c/muxes/i2c-mux-gpmux.c

diff --git a/drivers/i2c/muxes/Kconfig b/drivers/i2c/muxes/Kconfig
index 10b3d17ae3ea..5fb34f24 100644
--- a/drivers/i2c/muxes/Kconfig
+++ b/drivers/i2c/muxes/Kconfig
@@ -30,6 +30,19 @@ config I2C_MUX_GPIO
  This driver can also be built as a module.  If so, the module
  will be called i2c-mux-gpio.
 
+config I2C_MUX_GPMUX
+   tristate "General Purpose I2C multiplexer"
+   select MULTIPLEXER
+   depends on OF
+   help
+ If you say yes to this option, support will be included for a
+ general purpose I2C multiplexer. This driver provides access to
+ I2C busses connected through a MUX, which in turn is controlled
+ by a MUX-controller from the MUX subsystem.
+
+ This driver can also be built as a module.  If so, the module
+ will be called i2c-mux-gpmux.
+
 config I2C_MUX_PCA9541
tristate "NXP PCA9541 I2C Master Selector"
help
diff --git a/drivers/i2c/muxes/Makefile b/drivers/i2c/muxes/Makefile
index 9948fa45037f..af43c6c3e861 100644
--- a/drivers/i2c/muxes/Makefile
+++ b/drivers/i2c/muxes/Makefile
@@ -6,6 +6,7 @@ obj-$(CONFIG_I2C_ARB_GPIO_CHALLENGE)+= 
i2c-arb-gpio-challenge.o
 obj-$(CONFIG_I2C_DEMUX_PINCTRL)+= i2c-demux-pinctrl.o
 
 obj-$(CONFIG_I2C_MUX_GPIO) += i2c-mux-gpio.o
+obj-$(CONFIG_I2C_MUX_GPMUX)+= i2c-mux-gpmux.o
 obj-$(CONFIG_I2C_MUX_MLXCPLD)  += i2c-mux-mlxcpld.o
 obj-$(CONFIG_I2C_MUX_PCA9541)  += i2c-mux-pca9541.o
 obj-$(CONFIG_I2C_MUX_PCA954x)  += i2c-mux-pca954x.o
diff --git a/drivers/i2c/muxes/i2c-mux-gpmux.c 
b/drivers/i2c/muxes/i2c-mux-gpmux.c
new file mode 100644
index ..fb23b2278462
--- /dev/null
+++ b/drivers/i2c/muxes/i2c-mux-gpmux.c
@@ -0,0 +1,173 @@
+/*
+ * General Purpose I2C multiplexer
+ *
+ * Copyright (C) 2017 Axentia Technologies AB
+ *
+ * Author: Peter Rosin 
+ *
+ * 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 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+struct mux {
+   struct mux_control *control;
+
+   bool do_not_deselect;
+};
+
+static int i2c_mux_select(struct i2c_mux_core *muxc, u32 chan)
+{
+   struct mux *mux = i2c_mux_priv(muxc);
+   int ret;
+
+   ret = mux_control_select(mux->control, chan);
+   mux->do_not_deselect = ret < 0;
+
+   return ret;
+}
+
+static int i2c_mux_deselect(struct i2c_mux_core *muxc, u32 chan)
+{
+   struct mux *mux = i2c_mux_priv(muxc);
+
+   if (mux->do_not_deselect)
+   return 0;
+
+   return mux_control_deselect(mux->control);
+}
+
+static struct i2c_adapter *mux_parent_adapter(struct device *dev)
+{
+   struct device_node *np = dev->of_node;
+   struct device_node *parent_np;
+   struct i2c_adapter *parent;
+
+   parent_np = of_parse_phandle(np, "i2c-parent", 0);
+   if (!parent_np) {
+   dev_err(dev, "Cannot parse i2c-parent\n");
+   return ERR_PTR(-ENODEV);
+   }
+   parent = of_find_i2c_adapter_by_node(parent_np);
+   of_node_put(parent_np);
+   if (!parent)
+   return ERR_PTR(-EPROBE_DEFER);
+
+   return parent;
+}
+
+static const struct of_device_id i2c_mux_of_match[] = {
+   { .compatible = "i2c-mux", },
+   {},
+};
+MODULE_DEVICE_TABLE(of, i2c_mux_of_match);
+
+static int i2c_mux_probe(struct platform_device *pdev)
+{
+   struct device *dev = >dev;
+   struct device_node *np = dev->of_node;
+   struct device_node *child;
+   struct i2c_mux_core *muxc;
+   struct mux *mux;
+   struct i2c_adapter *parent;
+   int children;
+   int ret;
+
+   if (!np)
+   return -ENODEV;
+
+   mux = devm_kzalloc(dev, sizeof(*mux), GFP_KERNEL);
+   if (!mux)
+   return -ENOMEM;
+
+   mux->control = devm_mux_control_get(dev, NULL);
+   if (IS_ERR(mux->control)) {
+   if (PTR_ERR(mux->control) != -EPROBE_DEFER)
+   dev_err(dev, "failed to get control-mux\n");
+   return PTR_ERR(mux->control);
+   }
+
+   parent = mux_parent_adapter(dev);
+   if (IS_ERR(parent)) {
+   if (PTR_ERR(parent) != -EPROBE_DEFER)
+   

[PATCH v13 06/10] iio: multiplexer: new iio category and iio-mux driver

[Peter Rosin]

When a multiplexer changes how an iio device behaves (for example
by feeding different signals to an ADC), this driver can be used
to create one virtual iio channel for each multiplexer state.

Depends on the generic multiplexer subsystem.

Cache any ext_info values from the parent iio channel, creating a private
copy of the ext_info attributes for each multiplexer state/channel.

Reviewed-by: Jonathan Cameron 
Signed-off-by: Peter Rosin 
---
 MAINTAINERS   |   1 +
 drivers/iio/Kconfig   |   1 +
 drivers/iio/Makefile  |   1 +
 drivers/iio/multiplexer/Kconfig   |  18 ++
 drivers/iio/multiplexer/Makefile  |   6 +
 drivers/iio/multiplexer/iio-mux.c | 459 ++
 6 files changed, 486 insertions(+)
 create mode 100644 drivers/iio/multiplexer/Kconfig
 create mode 100644 drivers/iio/multiplexer/Makefile
 create mode 100644 drivers/iio/multiplexer/iio-mux.c

diff --git a/MAINTAINERS b/MAINTAINERS
index 4af912305d2c..23cfd5bc2158 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6365,6 +6365,7 @@ M:Peter Rosin 
 L: linux-...@vger.kernel.org
 S: Maintained
 F: Documentation/devicetree/bindings/iio/multiplexer/iio-mux.txt
+F: drivers/iio/multiplexer/iio-mux.c
 
 IIO SUBSYSTEM AND DRIVERS
 M: Jonathan Cameron 
diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
index a918270d6f54..b3c8c6ef0dff 100644
--- a/drivers/iio/Kconfig
+++ b/drivers/iio/Kconfig
@@ -83,6 +83,7 @@ source "drivers/iio/humidity/Kconfig"
 source "drivers/iio/imu/Kconfig"
 source "drivers/iio/light/Kconfig"
 source "drivers/iio/magnetometer/Kconfig"
+source "drivers/iio/multiplexer/Kconfig"
 source "drivers/iio/orientation/Kconfig"
 if IIO_TRIGGER
source "drivers/iio/trigger/Kconfig"
diff --git a/drivers/iio/Makefile b/drivers/iio/Makefile
index 33fa4026f92c..93c769cd99bf 100644
--- a/drivers/iio/Makefile
+++ b/drivers/iio/Makefile
@@ -28,6 +28,7 @@ obj-y += humidity/
 obj-y += imu/
 obj-y += light/
 obj-y += magnetometer/
+obj-y += multiplexer/
 obj-y += orientation/
 obj-y += potentiometer/
 obj-y += potentiostat/
diff --git a/drivers/iio/multiplexer/Kconfig b/drivers/iio/multiplexer/Kconfig
new file mode 100644
index ..70a044510686
--- /dev/null
+++ b/drivers/iio/multiplexer/Kconfig
@@ -0,0 +1,18 @@
+#
+# Multiplexer drivers
+#
+# When adding new entries keep the list in alphabetical order
+
+menu "Multiplexers"
+
+config IIO_MUX
+   tristate "IIO multiplexer driver"
+   select MULTIPLEXER
+   depends on OF
+   help
+ Say yes here to build support for the IIO multiplexer.
+
+ To compile this driver as a module, choose M here: the
+ module will be called iio-mux.
+
+endmenu
diff --git a/drivers/iio/multiplexer/Makefile b/drivers/iio/multiplexer/Makefile
new file mode 100644
index ..68be3c4abd07
--- /dev/null
+++ b/drivers/iio/multiplexer/Makefile
@@ -0,0 +1,6 @@
+#
+# Makefile for industrial I/O multiplexer drivers
+#
+
+# When adding new entries keep the list in alphabetical order
+obj-$(CONFIG_IIO_MUX) += iio-mux.o
diff --git a/drivers/iio/multiplexer/iio-mux.c 
b/drivers/iio/multiplexer/iio-mux.c
new file mode 100644
index ..bab9e6902090
--- /dev/null
+++ b/drivers/iio/multiplexer/iio-mux.c
@@ -0,0 +1,459 @@
+/*
+ * IIO multiplexer driver
+ *
+ * Copyright (C) 2017 Axentia Technologies AB
+ *
+ * Author: Peter Rosin 
+ *
+ * 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 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+struct mux_ext_info_cache {
+   char *data;
+   ssize_t size;
+};
+
+struct mux_child {
+   struct mux_ext_info_cache *ext_info_cache;
+};
+
+struct mux {
+   int cached_state;
+   struct mux_control *control;
+   struct iio_channel *parent;
+   struct iio_dev *indio_dev;
+   struct iio_chan_spec *chan;
+   struct iio_chan_spec_ext_info *ext_info;
+   struct mux_child *child;
+};
+
+static int iio_mux_select(struct mux *mux, int idx)
+{
+   struct mux_child *child = >child[idx];
+   struct iio_chan_spec const *chan = >chan[idx];
+   int ret;
+   int i;
+
+   ret = mux_control_select(mux->control, chan->channel);
+   if (ret < 0) {
+   mux->cached_state = -1;
+   return ret;
+   }
+
+   if (mux->cached_state == chan->channel)
+   return 0;
+
+   if (chan->ext_info) {
+   for (i = 0; chan->ext_info[i].name; ++i) {
+   const char *attr = chan->ext_info[i].name;
+   struct mux_ext_info_cache *cache;
+
+   cache = >ext_info_cache[i];
+
+   if (cache->size < 0)
+

[PATCH v13 10/10] mux: adg792a: add mux controller driver for ADG792A/G

[Peter Rosin]

Analog Devices ADG792A/G is a triple 4:1 mux.

Reviewed-by: Jonathan Cameron 
Signed-off-by: Peter Rosin 
---
 drivers/mux/Kconfig   |  12 
 drivers/mux/Makefile  |   1 +
 drivers/mux/mux-adg792a.c | 141 ++
 3 files changed, 154 insertions(+)
 create mode 100644 drivers/mux/mux-adg792a.c

diff --git a/drivers/mux/Kconfig b/drivers/mux/Kconfig
index 41dfe08ead84..86668b4d2fc5 100644
--- a/drivers/mux/Kconfig
+++ b/drivers/mux/Kconfig
@@ -17,6 +17,18 @@ menuconfig MULTIPLEXER
 
 if MULTIPLEXER
 
+config MUX_ADG792A
+   tristate "Analog Devices ADG792A/ADG792G Multiplexers"
+   depends on I2C
+   help
+ ADG792A and ADG792G Wide Bandwidth Triple 4:1 Multiplexers
+
+ The driver supports both operating the three multiplexers in
+ parallel and operating them independently.
+
+ To compile the driver as a module, choose M here: the module will
+ be called mux-adg792a.
+
 config MUX_GPIO
tristate "GPIO-controlled Multiplexer"
depends on OF && GPIOLIB
diff --git a/drivers/mux/Makefile b/drivers/mux/Makefile
index bb16953f6290..b00a7d37d2fb 100644
--- a/drivers/mux/Makefile
+++ b/drivers/mux/Makefile
@@ -3,4 +3,5 @@
 #
 
 obj-$(CONFIG_MULTIPLEXER)  += mux-core.o
+obj-$(CONFIG_MUX_ADG792A)  += mux-adg792a.o
 obj-$(CONFIG_MUX_GPIO) += mux-gpio.o
diff --git a/drivers/mux/mux-adg792a.c b/drivers/mux/mux-adg792a.c
new file mode 100644
index ..58c0ecf49a4a
--- /dev/null
+++ b/drivers/mux/mux-adg792a.c
@@ -0,0 +1,141 @@
+/*
+ * Multiplexer driver for Analog Devices ADG792A/G Triple 4:1 mux
+ *
+ * Copyright (C) 2017 Axentia Technologies AB
+ *
+ * Author: Peter Rosin 
+ *
+ * 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 
+#include 
+#include 
+#include 
+
+#define ADG792A_LDSW   BIT(0)
+#define ADG792A_RESETB BIT(1) /* active low, reset when zero */
+#define ADG792A_DISABLE(mux)   (0x50 | (mux))
+#define ADG792A_DISABLE_ALL(0x5f)
+#define ADG792A_MUX(mux, state)(0xc0 | (((mux) + 1) << 2) | (state))
+#define ADG792A_MUX_ALL(state) (0xc0 | (state))
+
+static int adg792a_set(struct mux_control *mux, int state)
+{
+   struct i2c_client *i2c = to_i2c_client(mux->chip->dev.parent);
+   u8 cmd;
+
+   if (mux->chip->controllers == 1) {
+   /* parallel mux controller operation */
+   if (state == MUX_IDLE_DISCONNECT)
+   cmd = ADG792A_DISABLE_ALL;
+   else
+   cmd = ADG792A_MUX_ALL(state);
+   } else {
+   unsigned int controller = mux_control_get_index(mux);
+
+   if (state == MUX_IDLE_DISCONNECT)
+   cmd = ADG792A_DISABLE(controller);
+   else
+   cmd = ADG792A_MUX(controller, state);
+   }
+
+   return i2c_smbus_write_byte_data(i2c, cmd,
+ADG792A_RESETB | ADG792A_LDSW);
+}
+
+static const struct mux_control_ops adg792a_ops = {
+   .set = adg792a_set,
+};
+
+static int adg792a_probe(struct i2c_client *i2c,
+const struct i2c_device_id *id)
+{
+   struct device *dev = >dev;
+   struct mux_chip *mux_chip;
+   u32 cells;
+   int ret;
+   int i;
+
+   ret = of_property_read_u32(dev->of_node, "#mux-control-cells", );
+   if (ret < 0)
+   return ret;
+   if (cells >= 2)
+   return -EINVAL;
+
+   mux_chip = devm_mux_chip_alloc(dev, cells ? 3 : 1, 0);
+   if (!mux_chip)
+   return -ENOMEM;
+
+   mux_chip->ops = _ops;
+
+   ret = i2c_smbus_write_byte_data(i2c, ADG792A_DISABLE_ALL,
+   ADG792A_LDSW);
+   if (ret < 0)
+   return ret;
+
+   for (i = 0; i < mux_chip->controllers; ++i) {
+   struct mux_control *mux = _chip->mux[i];
+   s32 idle_state;
+
+   mux->states = 4;
+
+   ret = of_property_read_u32_index(dev->of_node, "idle-state", i,
+(s32 *)_state);
+   if (ret < 0)
+   continue;
+
+   switch (idle_state) {
+   case 0 ... 4:
+   case MUX_IDLE_DISCONNECT:
+   mux_chip->mux[i].idle_state = idle_state;
+   break;
+   case MUX_IDLE_AS_IS:
+   break;
+   default:
+   dev_err(dev, "invalid idle-state %d\n", idle_state);
+   return -EINVAL;
+   }
+   }
+
+   ret = devm_mux_chip_register(dev, mux_chip);
+   if (ret < 0)
+   return ret;
+
+   if (cells)
+  

[PATCH v13 05/10] dt-bindings: iio: io-channel-mux: document io-channel-mux bindings

[Peter Rosin]

Describe how a multiplexer can be used to select which signal is fed to
an io-channel.

Acked-by: Jonathan Cameron 
Acked-by: Rob Herring 
Signed-off-by: Peter Rosin 
---
 .../bindings/iio/multiplexer/io-channel-mux.txt| 39 ++
 MAINTAINERS|  6 
 2 files changed, 45 insertions(+)
 create mode 100644 
Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt

diff --git 
a/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt 
b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt
new file mode 100644
index ..c82794002595
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/multiplexer/io-channel-mux.txt
@@ -0,0 +1,39 @@
+I/O channel multiplexer bindings
+
+If a multiplexer is used to select which hardware signal is fed to
+e.g. an ADC channel, these bindings describe that situation.
+
+Required properties:
+- compatible : "io-channel-mux"
+- io-channels : Channel node of the parent channel that has multiplexed
+   input.
+- io-channel-names : Should be "parent".
+- #address-cells = <1>;
+- #size-cells = <0>;
+- mux-controls : Mux controller node to use for operating the mux
+- channels : List of strings, labeling the mux controller states.
+
+For each non-empty string in the channels property, an io-channel will
+be created. The number of this io-channel is the same as the index into
+the list of strings in the channels property, and also matches the mux
+controller state. The mux controller state is described in
+../mux/mux-controller.txt
+
+Example:
+   mux: mux-controller {
+   compatible = "mux-gpio";
+   #mux-control-cells = <0>;
+
+   mux-gpios = < 0 GPIO_ACTIVE_HIGH>,
+   < 1 GPIO_ACTIVE_HIGH>;
+   };
+
+   adc-mux {
+   compatible = "io-channel-mux";
+   io-channels = < 0>;
+   io-channel-names = "parent";
+
+   mux-controls = <>;
+
+   channels = "sync", "in", "system-regulator";
+   };
diff --git a/MAINTAINERS b/MAINTAINERS
index 591eba737678..4af912305d2c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6360,6 +6360,12 @@ F:   
Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
 F: Documentation/devicetree/bindings/iio/adc/envelope-detector.txt
 F: drivers/iio/adc/envelope-detector.c
 
+IIO MULTIPLEXER
+M: Peter Rosin 
+L: linux-...@vger.kernel.org
+S: Maintained
+F: Documentation/devicetree/bindings/iio/multiplexer/iio-mux.txt
+
 IIO SUBSYSTEM AND DRIVERS
 M: Jonathan Cameron 
 R: Hartmut Knaack 
-- 
2.1.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 v13 09/10] dt-bindings: mux-adg792a: document devicetree bindings for ADG792A/G mux

[Peter Rosin]

Analog Devices ADG792A/G is a triple 4:1 mux.

Acked-by: Jonathan Cameron 
Reviewed-by: Rob Herring 
Signed-off-by: Peter Rosin 
---
 .../devicetree/bindings/mux/adi,adg792a.txt| 75 ++
 1 file changed, 75 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mux/adi,adg792a.txt

diff --git a/Documentation/devicetree/bindings/mux/adi,adg792a.txt 
b/Documentation/devicetree/bindings/mux/adi,adg792a.txt
new file mode 100644
index ..96b787a69f50
--- /dev/null
+++ b/Documentation/devicetree/bindings/mux/adi,adg792a.txt
@@ -0,0 +1,75 @@
+Bindings for Analog Devices ADG792A/G Triple 4:1 Multiplexers
+
+Required properties:
+- compatible : "adi,adg792a" or "adi,adg792g"
+- #mux-control-cells : <0> if parallel (the three muxes are bound together
+  with a single mux controller controlling all three muxes), or <1> if
+  not (one mux controller for each mux).
+* Standard mux-controller bindings as described in mux-controller.txt
+
+Optional properties for ADG792G:
+- gpio-controller : if present, #gpio-cells below is required.
+- #gpio-cells : should be <2>
+ - First cell is the GPO line number, i.e. 0 or 1
+ - Second cell is used to specify active high (0)
+   or active low (1)
+
+Optional properties:
+- idle-state : if present, array of states that the mux controllers will have
+  when idle. The special state MUX_IDLE_AS_IS is the default and
+  MUX_IDLE_DISCONNECT is also supported.
+
+States 0 through 3 correspond to signals A through D in the datasheet.
+
+Example:
+
+   /*
+* Three independent mux controllers (of which one is used).
+* Mux 0 is disconnected when idle, mux 1 idles in the previously
+* selected state and mux 2 idles with signal B.
+*/
+{
+   mux: mux-controller@50 {
+   compatible = "adi,adg792a";
+   reg = <0x50>;
+   #mux-control-cells = <1>;
+
+   idle-state = ;
+   };
+   };
+
+   adc-mux {
+   compatible = "io-channel-mux";
+   io-channels = < 0>;
+   io-channel-names = "parent";
+
+   mux-controls = < 2>;
+
+   channels = "sync-1", "", "out";
+   };
+
+
+   /*
+* Three parallel muxes with one mux controller, useful e.g. if
+* the adc is differential, thus needing two signals to be muxed
+* simultaneously for correct operation.
+*/
+{
+   pmux: mux-controller@50 {
+   compatible = "adi,adg792a";
+   reg = <0x50>;
+   #mux-control-cells = <0>;
+
+   idle-state = <1>;
+   };
+   };
+
+   diff-adc-mux {
+   compatible = "io-channel-mux";
+   io-channels = < 0>;
+   io-channel-names = "parent";
+
+   mux-controls = <>;
+
+   channels = "sync-1", "", "out";
+   };
-- 
2.1.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 v13 07/10] dt-bindings: i2c: i2c-mux: document general purpose i2c-mux bindings

[Peter Rosin]

Describe how a general purpose multiplexer controller is used to mux an
i2c bus.

Acked-by: Jonathan Cameron 
Reviewed-by: Rob Herring 
Signed-off-by: Peter Rosin 
---
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt  | 99 ++
 1 file changed, 99 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt

diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt 
b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
new file mode 100644
index ..2907dab56298
--- /dev/null
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -0,0 +1,99 @@
+General Purpose I2C Bus Mux
+
+This binding describes an I2C bus multiplexer that uses a mux controller
+from the mux subsystem to route the I2C signals.
+
+  .-.  .-.
+  | dev |  | dev |
+..'-'  '-'
+| SoC|   ||
+||  .+'
+|   .--. |  .--+child bus A, on MUX value set to 0
+|   | I2C  |-|--| Mux  |
+|   '--' |  '--+---+child bus B, on MUX value set to 1
+|   .--. | |'--++.
+|   | MUX- | | |   |||
+|   | Ctrl |-|-+.-.  .-.  .-.
+|   '--' |  | dev |  | dev |  | dev |
+''  '-'  '-'  '-'
+
+Required properties:
+- compatible: i2c-mux
+- i2c-parent: The phandle of the I2C bus that this multiplexer's master-side
+  port is connected to.
+- mux-controls: The phandle of the mux controller to use for operating the
+  mux.
+* Standard I2C mux properties. See i2c-mux.txt in this directory.
+* I2C child bus nodes. See i2c-mux.txt in this directory. The sub-bus number
+  is also the mux-controller state described in ../mux/mux-controller.txt
+
+Optional properties:
+- mux-locked: If present, explicitly allow unrelated I2C transactions on the
+  parent I2C adapter at these times:
+   + during setup of the multiplexer
+   + between setup of the multiplexer and the child bus I2C transaction
+   + between the child bus I2C transaction and releasing of the multiplexer
+   + during releasing of the multiplexer
+  However, I2C transactions to devices behind all I2C multiplexers connected
+  to the same parent adapter that this multiplexer is connected to are blocked
+  for the full duration of the complete multiplexed I2C transaction (i.e.
+  including the times covered by the above list).
+  If mux-locked is not present, the multiplexer is assumed to be parent-locked.
+  This means that no unrelated I2C transactions are allowed on the parent I2C
+  adapter for the complete multiplexed I2C transaction.
+  The properties of mux-locked and parent-locked multiplexers are discussed
+  in more detail in Documentation/i2c/i2c-topology.
+
+For each i2c child node, an I2C child bus will be created. They will
+be numbered based on their order in the device tree.
+
+Whenever an access is made to a device on a child bus, the value set
+in the relevant node's reg property will be set as the state in the
+mux controller.
+
+Example:
+   mux: mux-controller {
+   compatible = "gpio-mux";
+   #mux-control-cells = <0>;
+
+   mux-gpios = < 0 GPIO_ACTIVE_HIGH>,
+   < 1 GPIO_ACTIVE_HIGH>;
+   };
+
+   i2c-mux {
+   compatible = "i2c-mux";
+   mux-locked;
+   i2c-parent = <>;
+
+   mux-controls = <>;
+
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   i2c@1 {
+   reg = <1>;
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   ssd1307: oled@3c {
+   compatible = "solomon,ssd1307fb-i2c";
+   reg = <0x3c>;
+   pwms = < 4 3000>;
+   reset-gpios = < 7 1>;
+   reset-active-low;
+   };
+   };
+
+   i2c@3 {
+   reg = <3>;
+   #address-cells = <1>;
+   #size-cells = <0>;
+
+   pca9555: pca9555@20 {
+   compatible = "nxp,pca9555";
+   gpio-controller;
+   #gpio-cells = <2>;
+   reg = <0x20>;
+   };
+   };
+   };
-- 
2.1.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 v13 01/10] devres: trivial whitespace fix

[Peter Rosin]

Everything else is indented with two spaces, so fix the odd one out.

Acked-by: Jonathan Cameron 
Signed-off-by: Peter Rosin 
---
 Documentation/driver-model/devres.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-model/devres.txt 
b/Documentation/driver-model/devres.txt
index bf34d5b3a733..efb8200819d6 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.txt
@@ -335,7 +335,7 @@ MEM
   devm_kzalloc()
 
 MFD
- devm_mfd_add_devices()
+  devm_mfd_add_devices()
 
 PER-CPU MEM
   devm_alloc_percpu()
-- 
2.1.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 v13 00/10] mux controller abstraction and iio/i2c muxes

[Peter Rosin]

Hi Greg!

Please apply.

This adds a new mux controller subsystem with an interface for accessing
mux controllers, along with two drivers providing the interface (gpio
and adg792) and two consumers (iio and i2c). This is done in such a way
that several consumers can independently access the same mux controller
if one controller controls several multiplexers, thus allowing sharing.
But sharing is by no means required, of course. It is perfectly fine to
have a single consumer of a dedicated mux controller controlling only
one mux for said consumer.

The prediction is that the typical use case will be for gpio-based muxing
(which is also what drove the development), where the below schematics
show the flexibility with one gpio-based mux controller being shared by
the iio-mux and i2c-mux-gpmux drivers.

..
|GPO0|--.
|GPO1|. |
||| |
|| .---.
|| |dg4052a|
|| |   |
|ADC0|-|XX0| signal X0
|| | X1| signal X1
|| | X2| signal X2
|| | X3| signal X3
|| |   |
|SDA0|-|YY0| i2c segment Y0
|SCL0|--.  | Y1| i2c segment Y1
''  |  | Y2| i2c segment Y2
|  | Y3| i2c segment Y3
|  '---'
|0 1 2 3   (feed SCL0 to each of
|| | | |the 4 muxed segments)
'+-+-+-'

GPO0 and GPO1 may also be fed to further parallel muxers, which is perhaps
desired in a real application to minimize digital noise from the i2c Y
channel leaking into the analog X channel. I.e. it might be a good idea
to separate the analog and digital signals...

And the below hypothetical schematics indicate something similar but using
the i2c-based adg792a multiplexer instead.

..
|SDA0|--.
|SCL0|. |
||| |
|| .---.
|| |adg792a|
|| |   |
|ADC0|-|D1  S1A| signal S1A
|| |S1B| signal S1B
|| |S1C| signal S1C
|| |S1D| signal S1D
|| |   |
|SDA1|---+-|D2  S2A| i2c segment S2A
|SCL1|-. | |S2B| i2c segment S2B
'' | | |S2C| i2c segment S2C
   | | |S2D| i2c segment S2D
   | | |   |
   | '-|D3  S3A| i2c segment S3A
   |   |S3B| i2c segment S3B
   |   |S3C| i2c segment S3C
   |   |S3D| i2c segment S3D
   |   '---'
   | A B C D   A B C D  (feed SCL1 to each of
   | | | | |   | | | |   the 8 muxed segments)
   '-+-+-+-+---+-+-+-'


v12 -> v13 changes
- Philipp Zabel noticed a bad compatible string in the gpio muxer.
  I amended patch 3/10 with his patch.
- Fixed reversed sense of the reset bit in the adg792 muxer (patch 10/10).

v11 -> v12 changes
- patches 11 and 12 folded into patches 6 and 3 respectively.

v10 -> v11 changes
- added a fixes-tag and an ack from Jonathan on patch 11
- added a new patch (12) with a fix for messed up error path reported
  by Paul Gortmaker.
- fixed some editorial nitpicks in the documentation comments in patch 3.

v9 -> v10 changes
- rebased onto v4.11-rc1
- added reviewed-by tags from Rob on patches 7 and 9
- added a new patch (11) with a fix for an unsigned compare with less than
  zero detected by CoverityScan and reported by Colin Ian King
- allowed the mux core to be built as a module, after discussion with Paul
  Gortmaker
- added explicit includes of linux/export.h and linux/init.h from the mux
  core, also noted by Paul
- fixed trivial whitespace issue in drivers/mux/Makefile
- added trailing '>' after my mail address in MODULE_AUTHOR, which was missing
  in all new modules in drivers/mux

v8 -> v9 changes
- dropped the suffix from the compatible string of the i2c-mux-simple
  binding (was ,mux-locked or ,parent-locked) and add an optional
  mux-locked property instead to change the desired locking behavior
  from the default parent-locked
- add description of the difference between mux-locked and parent-locked
- renamed i2c-mux-simple to i2c-mux (bindings for this general purpose
  i2c mux are in i2c-mux-gpmux.txt since i2c-mux.txt is already occupied
  by the common i2c-mux bindings)
- changed compatible from mux-gpio to gpio-mux
- changed bindings for idle-state back to a single array, but add defines
  for as-is and hi-Z thus avoiding magic numbers
- make use of the above defines in the code as well
- make idle-state a common mux property described in mux-controller.txt
  instead of repeating the info in individual mux controller bindings
- drop the adi,parallel property from the adg792 bindings and piggy-back
  on the #mux-control-cells property
- refrain from using the compatible string as node name
- dropped the 

Re: [PATCH] docs: conf.py: increase recursion limit

[Markus Heiser]

Am 13.04.2017 um 15:29 schrieb Mauro Carvalho Chehab :

> Em Thu, 13 Apr 2017 14:55:03 +0200
> Markus Heiser  escreveu:
> 
>> On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:
>>> The default recursion limit is not good enough to handle
>>> complex books. I'm sometimes receiving this error message:
>>> 
>>> sphinx.errors.SphinxParallelError: RecursionError: maximum recursion 
>>> depth exceeded while pickling an object
>>> 
>>> or those:
>>> 
>>> maximum recursion depth exceeded while calling a Python object
>>> This can happen with very large or deeply nested source files.  You can 
>>> carefully increase the default Python recursion limit of 1000 in conf.py 
>>> with e.g.:
>>> import sys; sys.setrecursionlimit(1500)
>>> 
>> 
>> Is this behavior reproducible?
> 
> I noticed the issue when building the docs with Sphinx 1.4.9 with
> my ABI patches, after adding xref links to it.
> 
> What I suspect is that Sphinx use some sort of fragile recursion
> algorithm to parse cross references.

   Or the the generated refs are absurd ;)

I haven't found the technical problem in detail, but I made some
test and this is what I observed; Sometimes even a "clean":

 make DOCBOOKS= clean htmldocs

fails with recursion error. I also realized that this behavior
is only about the generated ABI docs. So I looked at what the
Perl script generates:

  ./scripts/get_abi.pl rest --dir Documentation/ABI/testing

It generates horrible titles, containing more than 4000 characters!
I mean titles like the one shown in "" below.
Which ends in HTML links like the one below.

OK, we can discuss why Sphinx have problems handling such titles
and refs but:
   
 at this point I stop digging any deeper ;)

IMO: this is not the way, we can include ABI into the reST doc

-- Markus --

A typical HTML link: 

http://www.infradead.org/~mchehab/kernel_docs/admin-guide/abi-testing.html?highlight=rising%20period#sys-events-in-accel-thresh-rising-value-sys-events-in-accel-thresh-falling-value-sys-events-in-accel-x-raw-thresh-rising-value-sys-events-in-accel-x-raw-thresh-falling-value-sys-events-in-accel-y-raw-thresh-rising-value-sys-events-in-accel-y-raw-thresh-falling-value-sys-events-in-accel-z-raw-thresh-rising-value-sys-events-in-accel-z-raw-thresh-falling-value-sys-events-in-anglvel-x-raw-thresh-rising-value-sys-events-in-anglvel-x-raw-thresh-falling-value-sys-events-in-anglvel-y-raw-thresh-rising-value-sys-events-in-anglvel-y-raw-thresh-falling-value-sys-events-in-anglvel-z-raw-thresh-rising-value-sys-events-in-anglvel-z-raw-thresh-falling-value-sys-events-in-magn-x-raw-thresh-rising-value-sys-events-in-magn-x-raw-thresh-falling-value-sys-events-in-magn-y-raw-thresh-rising-value-sys-events-in-magn-y-raw-thresh-falling-value-sys-events-in-magn-z-raw-thresh-rising-value-sys-events-in-magn-z-raw-thresh-falling-value-sys-events-in-rot-from-north-magnetic-raw-thresh-rising-value-sys-events-in-rot-from-north-magnetic-raw-thresh-falling-value-sys-events-in-rot-from-north-true-raw-thresh-rising-value-sys-events-in-rot-from-north-true-raw-thresh-falling-value-sys-events-in-rot-from-north-magnetic-tilt-comp-raw-thresh-rising-value-sys-events-in-rot-from-north-magnetic-tilt-comp-raw-thresh-falling-value-sys-events-in-rot-from-north-true-tilt-comp-raw-thresh-rising-value-sys-events-in-rot-from-north-true-tilt-comp-raw-thresh-falling-value-sys-events-in-voltagey-supply-raw-thresh-rising-value-sys-events-in-voltagey-supply-raw-thresh-falling-value-sys-events-in-voltagey-raw-thresh-rising-value-sys-events-in-voltagey-raw-thresh-falling-value-sys-events-in-tempy-raw-thresh-rising-value-sys-events-in-tempy-raw-thresh-falling-value-sys-events-in-illuminance0-thresh-falling-value-sys-events-in-illuminance0-thresh-rising-value-sys-events-in-proximity0-thresh-falling-value-sys-events-in-proximity0-thresh-rising-value



And here is one of those horrible reST titles:

 --

.. _abi_sys_events_in_accel_x_thresh_rising_period:

/sys/.../events/in\_accel\_x\_thresh\_rising\_period, 
/sys/.../events/in\_accel\_x\_thresh\_falling\_period, 
/sys/.../events/in\_accel\_x\_roc\_rising\_period, 
/sys/.../events/in\_accel\_x\_roc\_falling\_period, 
/sys/.../events/in\_accel\_y\_thresh\_rising\_period, 
/sys/.../events/in\_accel\_y\_thresh\_falling\_period, 
/sys/.../events/in\_accel\_y\_roc\_rising\_period, 
/sys/.../events/in\_accel\_y\_roc\_falling\_period, 
/sys/.../events/in\_accel\_z\_thresh\_rising\_period, 
/sys/.../events/in\_accel\_z\_thresh\_falling\_period, 
/sys/.../events/in\_accel\_z\_roc\_rising\_period, 
/sys/.../events/in\_accel\_z\_roc\_falling\_period, 
/sys/.../events/in\_anglvel\_x\_thresh\_rising\_period, 
/sys/.../events/in\_anglvel\_x\_thresh\_falling\_period, 
/sys/.../events/in\_anglvel\_x\_roc\_rising\_period, 
/sys/.../events/in\_anglvel\_x\_roc\_falling\_period, 
/sys/.../events/in\_anglvel\_y\_thresh\_rising\_period, 

Re: [PATCH 1/3] rtmutex: comments update

[Steven Rostedt]

On Thu, 13 Apr 2017 22:02:52 +0800
Alex Shi  wrote:

> The rt-mutex documents didn't gotten meaningful update from its first
> version. Even after owner's pending bit was removed in commit 8161239a8bcc
> ("rtmutex: Simplify PI algorithm and make highest prio task get lock")
> and priority list 'plist' changed to rbtree. So the documents are far
> late of real code.

BTW, there is still technically a "Pending Owner", it's just not called
that anymore. The pending owner happens to be the top_waiter of a lock
that has no owner and has been woken up to grab the lock. This change
simplified the code. The document should reflect this point.

-- Steve

--
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] docs: conf.py: increase recursion limit

[Jonathan Corbet]

On Thu, 13 Apr 2017 14:55:03 +0200
Markus Heiser  wrote:

> Sphinx caches the doctree (they call it "pickling"). On re-compile, this
> cached doctree is readed in and changes from the rst-files are merged into
> this doctree. After, the "updated" doctree is pickled (cached) again.
> This procedere is fragil in some circumstances.

Sigh.  My experience with the pickle module says that it's always
fragile.  It looks like a nice way to serialize objects, but there's a
lot that can go wrong.

It would be good to understand what's going wrong here, though; I've
never seen this error either.  I'm not opposed to raising the limit, but
I do wonder if we're papering over the problem and missing the real fix.

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

Re: [PATCH v2 02/11] ABI: fix some syntax issues at the ABI database

[Andrew Donnellan]

On 13/04/17 20:08, Mauro Carvalho Chehab wrote:

diff --git a/Documentation/ABI/testing/sysfs-class-cxl 
b/Documentation/ABI/testing/sysfs-class-cxl
index 640f65e79ef1..d0b32452dfe1 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -1,6 +1,6 @@
-Note: Attributes that are shared between devices are stored in the directory
-pointed to by the symlink device/.
-Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
+Please notice that attributes that are shared between devices are stored in
+the directory pointed to by the symlink device/.
+For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
 /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.


If you end up respinning this, I'd prefer "Note that" or "Please note 
that" rather than "Please notice". Otherwise, for cxl:


Reviewed-by: Andrew Donnellan 

--
Andrew Donnellan  OzLabs, ADL Canberra
andrew.donnel...@au1.ibm.com  IBM Australia Limited

--
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 1/3] rtmutex: comments update

[Alex Shi]

The rt-mutex documents didn't gotten meaningful update from its first
version. Even after owner's pending bit was removed in commit 8161239a8bcc
("rtmutex: Simplify PI algorithm and make highest prio task get lock")
and priority list 'plist' changed to rbtree. So the documents are far
late of real code.

So update it to latest code and make it meaningful.

Signed-off-by: Alex Shi 
Cc: Steven Rostedt 
Cc: Sebastian Siewior 
To: linux-doc@vger.kernel.org
To: linux-ker...@vger.kernel.org
To: Jonathan Corbet 
To: Ingo Molnar 
To: Peter Zijlstra 
Cc: Thomas Gleixner 
---
 Documentation/locking/rt-mutex-design.txt | 438 ++
 Documentation/locking/rt-mutex.txt|  32 ++-
 2 files changed, 153 insertions(+), 317 deletions(-)

diff --git a/Documentation/locking/rt-mutex-design.txt 
b/Documentation/locking/rt-mutex-design.txt
index 8666070..5a1c0ca 100644
--- a/Documentation/locking/rt-mutex-design.txt
+++ b/Documentation/locking/rt-mutex-design.txt
@@ -97,9 +97,9 @@ waiter   - A waiter is a struct that is stored on the stack 
of a blocked
a process being blocked on the mutex, it is fine to allocate
the waiter on the process's stack (local variable).  This
structure holds a pointer to the task, as well as the mutex that
-   the task is blocked on.  It also has the plist node structures to
-   place the task in the waiter_list of a mutex as well as the
-   pi_list of a mutex owner task (described below).
+  the task is blocked on.  It also has a rbtree node structures to
+  place the task in the waiters of a mutex as well as the pi_waiters
+  of a mutex owner task (described below).
 
waiter is sometimes used in reference to the task that is waiting
on a mutex. This is the same as waiter->task.
@@ -179,53 +179,34 @@ again.
  |
F->L5-+
 
-
-Plist
--
-
-Before I go further and talk about how the PI chain is stored through lists
-on both mutexes and processes, I'll explain the plist.  This is similar to
-the struct list_head functionality that is already in the kernel.
-The implementation of plist is out of scope for this document, but it is
-very important to understand what it does.
-
-There are a few differences between plist and list, the most important one
-being that plist is a priority sorted linked list.  This means that the
-priorities of the plist are sorted, such that it takes O(1) to retrieve the
-highest priority item in the list.  Obviously this is useful to store processes
-based on their priorities.
-
-Another difference, which is important for implementation, is that, unlike
-list, the head of the list is a different element than the nodes of a list.
-So the head of the list is declared as struct plist_head and nodes that will
-be added to the list are declared as struct plist_node.
-
+If the G process has highest priority in the chain, any right lock owners
+need to increase its' priority as high as G.
 
 Mutex Waiter List
 -
 
 Every mutex keeps track of all the waiters that are blocked on itself. The 
mutex
-has a plist to store these waiters by priority.  This list is protected by
+has a rbtree to store these waiters by priority.  This tree is protected by
 a spin lock that is located in the struct of the mutex. This lock is called
-wait_lock.  Since the modification of the waiter list is never done in
+wait_lock.  Since the modification of the waiter tree is never done in
 interrupt context, the wait_lock can be taken without disabling interrupts.
 
 
-Task PI List
+Task PI Tree
 
 
-To keep track of the PI chains, each process has its own PI list.  This is
-a list of all top waiters of the mutexes that are owned by the process.
-Note that this list only holds the top waiters and not all waiters that are
+To keep track of the PI chains, each process has its own PI rbtree.  This is
+a tree of all top waiters of the mutexes that are owned by the process.
+Note that this tree only holds the top waiters and not all waiters that are
 blocked on mutexes owned by the process.
 
-The top of the task's PI list is always the highest priority task that
+The top of the task's PI tree is always the highest priority task that
 is waiting on a mutex that is owned by the task.  So if the task has
 inherited a priority, it will always be the priority of the task that is
-at the top of this list.
+at the top of this tree.
 
-This list is stored in the task structure of a process as a plist called
-pi_list.  This list is protected by a spin lock also in the task structure,
+This tree is stored in the task structure of a process as a rbtree called
+pi_waiters.  It is protected by a spin lock also in the task structure,
 called pi_lock.  This lock may also be taken 

Re: [PATCH] docs: conf.py: increase recursion limit

[Markus Heiser]

On 13.04.2017 15:29, Mauro Carvalho Chehab wrote:

Em Thu, 13 Apr 2017 14:55:03 +0200
Markus Heiser  escreveu:


On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:

The default recursion limit is not good enough to handle
complex books. I'm sometimes receiving this error message:

sphinx.errors.SphinxParallelError: RecursionError: maximum recursion 
depth exceeded while pickling an object

or those:

maximum recursion depth exceeded while calling a Python object
This can happen with very large or deeply nested source files.  You can 
carefully increase the default Python recursion limit of 1000 in conf.py with 
e.g.:
import sys; sys.setrecursionlimit(1500)



Is this behavior reproducible?

I also observed those errors in the past. But mostly, it turned
out that I was the problem ;)

Sphinx caches the doctree (they call it "pickling"). On re-compile, this
cached doctree is readed in and changes from the rst-files are merged into
this doctree. After, the "updated" doctree is pickled (cached) again.
This procedere is fragil in some circumstances.

E.g. Sphinx parses every rst-file in Documents/ and below (every!
not only those files refered in toctrees), if you have some C
corpses with rst-files in ... its all parsed into the doctree and
merged and pickled again.

E.g. re-compiling on a shares without a clean before, while different
Sphinx versions are installed on your hosts using this share. (IMO
merging the cached doctree with changes from rst-files is not stable
over Sphinx versions).


I noticed the issue when building the docs with Sphinx 1.4.9 with
my ABI patches, after adding xref links to it.


Ah, OK .. I hope I will find the time to test your patch in the
next days (may be there is something wrong with the xrefs, I have
to check).



What I suspect is that Sphinx use some sort of fragile recursion
algorithm to parse cross references.


This could be one reason .. cross refs are solved by using the (pickled
and updated) doctree. When such a doctree is damaged/fragil, solving
refs might end in (endless) recursion.


Increase it.


I recomend to increase the recusion-limit only, if we have a reproducible
scenario.


Why? Could this make it less stable?


No. Increasing the limit might slow down compilation, but it is not a instable.

Mostly we have some other problem when we need to increase the limit and
I want to identify/exclude the problem.

FYI: As far as I know, the default limit is mostly about 1k. The recursion
limit is not about Sphinx, it is about Python's stack:

  https://docs.python.org/3/library/sys.html#sys.setrecursionlimit

In my 15 years python experience I never needed to increase it (except some
very cruel and hackish scripts), so I have doubts; I it smells like fixing
the symptoms.

--Markus--

--
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] docs: conf.py: increase recursion limit

[Mauro Carvalho Chehab]

Em Thu, 13 Apr 2017 14:55:03 +0200
Markus Heiser  escreveu:

> On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:
> > The default recursion limit is not good enough to handle
> > complex books. I'm sometimes receiving this error message:
> >
> > sphinx.errors.SphinxParallelError: RecursionError: maximum recursion 
> > depth exceeded while pickling an object
> >
> > or those:
> >
> > maximum recursion depth exceeded while calling a Python object
> > This can happen with very large or deeply nested source files.  You can 
> > carefully increase the default Python recursion limit of 1000 in conf.py 
> > with e.g.:
> > import sys; sys.setrecursionlimit(1500)
> >  
> 
> Is this behavior reproducible?
> 
> I also observed those errors in the past. But mostly, it turned
> out that I was the problem ;)
> 
> Sphinx caches the doctree (they call it "pickling"). On re-compile, this
> cached doctree is readed in and changes from the rst-files are merged into
> this doctree. After, the "updated" doctree is pickled (cached) again.
> This procedere is fragil in some circumstances.
> 
> E.g. Sphinx parses every rst-file in Documents/ and below (every!
> not only those files refered in toctrees), if you have some C
> corpses with rst-files in ... its all parsed into the doctree and
> merged and pickled again.
> 
> E.g. re-compiling on a shares without a clean before, while different
> Sphinx versions are installed on your hosts using this share. (IMO
> merging the cached doctree with changes from rst-files is not stable
> over Sphinx versions).

I noticed the issue when building the docs with Sphinx 1.4.9 with
my ABI patches, after adding xref links to it.

What I suspect is that Sphinx use some sort of fragile recursion
algorithm to parse cross references.

> 
> 
> > Increase it.  
> 
> I recomend to increase the recusion-limit only, if we have a reproducible
> scenario.

Why? Could this make it less stable?

> 
> -- Markus --
> 
> 
> >
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/conf.py | 1 +
> >  1 file changed, 1 insertion(+)
> >
> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > index 45a0741b39ed..ff5a5979f5d5 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -19,6 +19,7 @@ import sphinx
> >  # Get Sphinx version
> >  major, minor, patch = sphinx.version_info[:3]
> >
> > +sys.setrecursionlimit(5000)
> >
> >  # If extensions (or modules to document with autodoc) are in another 
> > directory,
> >  # add these directories to sys.path here. If the directory is relative to 
> > the
> >  



Thanks,
Mauro
--
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] docs: conf.py: increase recursion limit

[Markus Heiser]

On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:

The default recursion limit is not good enough to handle
complex books. I'm sometimes receiving this error message:

sphinx.errors.SphinxParallelError: RecursionError: maximum recursion 
depth exceeded while pickling an object

or those:

maximum recursion depth exceeded while calling a Python object
This can happen with very large or deeply nested source files.  You can 
carefully increase the default Python recursion limit of 1000 in conf.py with 
e.g.:
import sys; sys.setrecursionlimit(1500)



Is this behavior reproducible?

I also observed those errors in the past. But mostly, it turned
out that I was the problem ;)

Sphinx caches the doctree (they call it "pickling"). On re-compile, this
cached doctree is readed in and changes from the rst-files are merged into
this doctree. After, the "updated" doctree is pickled (cached) again.
This procedere is fragil in some circumstances.

E.g. Sphinx parses every rst-file in Documents/ and below (every!
not only those files refered in toctrees), if you have some C
corpses with rst-files in ... its all parsed into the doctree and
merged and pickled again.

E.g. re-compiling on a shares without a clean before, while different
Sphinx versions are installed on your hosts using this share. (IMO
merging the cached doctree with changes from rst-files is not stable
over Sphinx versions).



Increase it.


I recomend to increase the recusion-limit only, if we have a reproducible
scenario.

-- Markus --




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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 45a0741b39ed..ff5a5979f5d5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -19,6 +19,7 @@ import sphinx
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]

+sys.setrecursionlimit(5000)

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the


--
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 v2 00/11] Documentation: Add ABI to the admin guide

[Mauro Carvalho Chehab]

Em Thu, 13 Apr 2017 07:08:43 -0300
Mauro Carvalho Chehab  escreveu:

> That's the third attempt to add support for the Kernel ABI
> at the Documentation's admin guide.
> 
> The first approach was based on a generic extension that
> calls a random script. This one is based on a new Sphinx
> extension with adds a symbol specific for parsing ABI
> symbols.
> 
> It adds a new script (scripts/get_abi.pl) with can either
> search for ABI symbols that match a regular expression or
> outputs the entire documentation found inside a directory
> as a ReST book.
> 
> Adding the ABI description to the Linux documentation is
> as easy as adding a tab like:
> 
>   .. kernel-abi:: $srctree/Documentation/ABI/obsolete
> 
> On version 3, I improved the script to better parse the
> ABI descriptions. On this version, it will identify if the
> description can be handled as a normal text. If so, it will
> escape characters that has special meaning on Sphinx.
> If it detects that the description syntax is too complex,
> it outputs inside a literal block.
> 
> Also on version 3, I opted to use 4 separate sections, one
> for each type of symbol. It also add an entry with the name
> of each ABI file, with has cross-references to the symbols
> defined on each file.
> 
> The parser was also improved to handle any content at the
> files that are before the ABI tags.

The HTML formatted result can be seen at:
http://www.infradead.org/~mchehab/kernel_docs/admin-guide/abi.html

And the PDF formatted result at (pages 151 to 565):
http://www.infradead.org/~mchehab/kernel_docs_pdf/linux-user.pdf

Thanks,
Mauro
--
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] docs: conf.py: increase recursion limit

[Mauro Carvalho Chehab]

The default recursion limit is not good enough to handle
complex books. I'm sometimes receiving this error message:

sphinx.errors.SphinxParallelError: RecursionError: maximum recursion 
depth exceeded while pickling an object

or those:

maximum recursion depth exceeded while calling a Python object
This can happen with very large or deeply nested source files.  You can 
carefully increase the default Python recursion limit of 1000 in conf.py with 
e.g.:
import sys; sys.setrecursionlimit(1500)

Increase it.

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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 45a0741b39ed..ff5a5979f5d5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -19,6 +19,7 @@ import sphinx
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
+sys.setrecursionlimit(5000)
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
-- 
2.9.3

--
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 v2 01/11] doc-rst: customize RTD theme; literal-block

[Mauro Carvalho Chehab]

From: Markus Heiser 

From: Markus Heiser 

Format the literal-block like other code-block elements, with 12px and a
line-high of 1.5.

Signed-off-by: Markus Heiser 
Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/sphinx-static/theme_overrides.css | 7 +++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/sphinx-static/theme_overrides.css 
b/Documentation/sphinx-static/theme_overrides.css
index d5764a4de5a2..7033d4c05e42 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -69,4 +69,11 @@
 .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
 color: inherit;
 }
+
+/* literal blocks (e.g. parsed-literal directive) */
+
+pre.literal-block {
+font-size: 12px;
+line-height: 1.5;
+}
 }
-- 
2.9.3

--
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 v2 09/11] scripts/get_abi.pl: split label naming from xref logic

[Mauro Carvalho Chehab]

Instead of using a ReST compilant label while parsing,
move the label to ReST output. That makes the parsing logic
more generic, allowing it to provide other types of output.

As a side effect, now all files used to generate the output
will be output. We can later add command line arguments to
filter.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/get_abi.pl | 94 ++
 1 file changed, 53 insertions(+), 41 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ba8a7466f896..d437e148b1c0 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -49,17 +49,23 @@ sub parse_abi {
my $name = $file;
$name =~ s,.*/,,;
 
+   my $nametag = "File $name";
+   $data{$nametag}->{what} = "File $name";
+   $data{$nametag}->{type} = "File";
+   $data{$nametag}->{file} = $name;
+   $data{$nametag}->{is_file} = 1;
+
my $type = $file;
$type =~ s,.*/(.*)/.*,$1,;
 
my $what;
my $new_what;
my $tag;
-   my $label;
my $ln;
-   my $has_file;
my $xrefs;
my $space;
+   my @labels;
+   my $label;
 
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
@@ -88,28 +94,13 @@ sub parse_abi {
parse_error($file, $ln, "What '$what' 
doesn't have a description", "") if ($what && !$data{$what}->{description});
 
$what = $content;
+   $label = $content;
$new_what = 1;
}
+   push @labels, [($content, $label)];
$tag = $new_tag;
 
-   if ($has_file) {
-   $label = "abi_" . $content . " ";
-   $label =~ tr/A-Z/a-z/;
-
-   # Convert special chars to "_"
-   $label =~s/[\x00-\x2f]+/_/g;
-   $label =~s/[\x3a-\x40]+/_/g;
-   $label =~s/[\x7b-\xff]+/_/g;
-   $label =~ s,_+,_,g;
-   $label =~ s,_$,,;
-
-   $data{$what}->{label} .= $label;
-
-   # Escape special chars from content
-   $content 
=~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
-
-   $xrefs .= "- :ref:`$content 
<$label>`\n\n";
-   }
+   push @{$data{$nametag}->{xrefs}}, [($content, 
$label)] if ($data{$nametag}->{what});
next;
}
 
@@ -117,6 +108,9 @@ sub parse_abi {
$tag = $new_tag;
 
if ($new_what) {
+   @{$data{$what}->{label}} = @labels if 
($data{$nametag}->{what});
+   @labels = ();
+   $label = "";
$new_what = 0;
 
$data{$what}->{type} = $type;
@@ -145,15 +139,8 @@ sub parse_abi {
}
 
# Store any contents before tags at the database
-   if (!$tag) {
-   next if (/^\n/);
-
-   my $my_what = "File $name";
-   $data{$my_what}->{what} = "File $name";
-   $data{$my_what}->{type} = "File";
-   $data{$my_what}->{file} = $name;
-   $data{$my_what}->{description} .= $_;
-   $has_file = 1;
+   if (!$tag && $data{$nametag}->{what}) {
+   $data{$nametag}->{description} .= $_;
next;
}
 
@@ -192,12 +179,8 @@ sub parse_abi {
# Everything else is error
parse_error($file, $ln, "Unexpected line:", $_);
}
+   $data{$nametag}->{description} =~ s/^\n+//;
close IN;
-
-   if ($has_file) {
-   my $my_what = "File $name";
-$data{$my_what}->{xrefs} = $xrefs;
-   }
 }
 
 # Outputs the output on ReST format
@@ -212,11 +195,22 @@ sub output_rest {
my $bar = $w;
$bar =~ s/./-/g;
 
-   if ($data{$what}->{label}) {
-   my @labels = split(/\s/, $data{$what}->{label});
-   foreach my $label (@labels) {
-   printf ".. _%s:\n\n", $label;
-   }
+   foreach my $p (@{$data{$what}->{label}}) {
+   my ($content, $label) = @{$p};
+   

[PATCH v2 03/11] ABI: sysfs-driver-hid: the "What" field doesn't parse fine

[Mauro Carvalho Chehab]

The What: field on this ABI description use a different
syntax than expected, causing it to not be properly parsed
by script.

Fix it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/testing/sysfs-driver-hid | 12 ++--
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-driver-hid 
b/Documentation/ABI/testing/sysfs-driver-hid
index 48942cacb0bf..a59533410871 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid
+++ b/Documentation/ABI/testing/sysfs-driver-hid
@@ -1,6 +1,6 @@
-What:  For USB devices : 
/sys/bus/usb/devices/-:./::./report_descriptor
-   For BT devices  : 
/sys/class/bluetooth/hci/::./report_descriptor
-   Symlink : 
/sys/class/hidraw/hidraw/device/report_descriptor
+What:  /sys/bus/usb/devices/-:./::./report_descriptor
+What:  
/sys/class/bluetooth/hci/::./report_descriptor
+What:  /sys/class/hidraw/hidraw/device/report_descriptor
 Date:  Jan 2011
 KernelVersion: 2.0.39
 Contact:   Alan Ott 
@@ -9,9 +9,9 @@ Description:When read, this file returns the device's raw 
binary HID
This file cannot be written.
 Users: HIDAPI library (http://www.signal11.us/oss/hidapi)
 
-What:  For USB devices : 
/sys/bus/usb/devices/-:./::./country
-   For BT devices  : 
/sys/class/bluetooth/hci/::./country
-   Symlink : /sys/class/hidraw/hidraw/device/country
+What:  /sys/bus/usb/devices/-:./::./country
+What:  
/sys/class/bluetooth/hci/::./country
+What:  /sys/class/hidraw/hidraw/device/country
 Date:  February 2015
 KernelVersion: 3.19
 Contact:   Olivier Gay 
-- 
2.9.3

--
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 v2 00/11] Documentation: Add ABI to the admin guide

[Mauro Carvalho Chehab]

That's the third attempt to add support for the Kernel ABI
at the Documentation's admin guide.

The first approach was based on a generic extension that
calls a random script. This one is based on a new Sphinx
extension with adds a symbol specific for parsing ABI
symbols.

It adds a new script (scripts/get_abi.pl) with can either
search for ABI symbols that match a regular expression or
outputs the entire documentation found inside a directory
as a ReST book.

Adding the ABI description to the Linux documentation is
as easy as adding a tab like:

.. kernel-abi:: $srctree/Documentation/ABI/obsolete

On version 3, I improved the script to better parse the
ABI descriptions. On this version, it will identify if the
description can be handled as a normal text. If so, it will
escape characters that has special meaning on Sphinx.
If it detects that the description syntax is too complex,
it outputs inside a literal block.

Also on version 3, I opted to use 4 separate sections, one
for each type of symbol. It also add an entry with the name
of each ABI file, with has cross-references to the symbols
defined on each file.

The parser was also improved to handle any content at the
files that are before the ABI tags.

The first 3 patches on this series fix some syntax errors
on some ABI description.

The next one makes sure that, when a table is present on
the description, the preceding line will end with a colon
(with is one of the ways the script uses to identify
complex layouts).

-

IMHO, we should add another ABI tag to allow using an
enriched text description, e. g. instead of:

Description:  foo

One could use, instead, something like:

ReST-description: foo

On such case, the script wouldn't need to escape the
description contents, as they can be just sent directly to
the ABI ReST output.

Markus Heiser (1):
  doc-rst: customize RTD theme; literal-block

Mauro Carvalho Chehab (10):
  ABI: fix some syntax issues at the ABI database
  ABI: sysfs-driver-hid: the "What" field doesn't parse fine
  ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
  ABI: better identificate tables
  scripts: add an script to parse the ABI files
  scripts/get_abi.pl: parse files with text at beginning
  scripts/get_abi.pl: avoid use literal blocks when not needed
  scripts/get_abi.pl: split label naming from xref logic
  scripts/get_abi.pl: add support for searching for ABI symbols
  doc-rst: add ABI documentation to the admin-guide book

 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra  |   2 +-
 Documentation/ABI/testing/pstore   |   2 +-
 .../testing/sysfs-bus-event_source-devices-format  |   2 +-
 .../ABI/testing/sysfs-bus-i2c-devices-hm6352   |   6 +-
 .../ABI/testing/sysfs-bus-iio-distance-srf08   |   4 +-
 .../ABI/testing/sysfs-bus-iio-proximity-as3935 |   4 +-
 .../ABI/testing/sysfs-bus-pci-devices-cciss|  22 +-
 .../ABI/testing/sysfs-bus-usb-devices-usbsevseg|  12 +-
 .../testing/sysfs-class-backlight-driver-lm3533|   6 +-
 Documentation/ABI/testing/sysfs-class-cxl  |   6 +-
 Documentation/ABI/testing/sysfs-class-devfreq  |   2 +-
 .../ABI/testing/sysfs-class-led-driver-lm3533  |   8 +-
 Documentation/ABI/testing/sysfs-class-leds-gt683r  |   4 +-
 Documentation/ABI/testing/sysfs-class-powercap |   2 +-
 Documentation/ABI/testing/sysfs-class-uwb_rc   |   6 -
 Documentation/ABI/testing/sysfs-driver-hid |  12 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone   |   2 +-
 Documentation/ABI/testing/sysfs-kernel-fscaps  |   2 +-
 Documentation/ABI/testing/sysfs-kernel-vmcoreinfo  |   2 +-
 Documentation/admin-guide/abi-obsolete.rst |  10 +
 Documentation/admin-guide/abi-removed.rst  |   4 +
 Documentation/admin-guide/abi-stable.rst   |  13 +
 Documentation/admin-guide/abi-testing.rst  |  19 +
 Documentation/admin-guide/abi.rst  |  11 +
 Documentation/admin-guide/index.rst|   1 +
 Documentation/conf.py  |   3 +-
 Documentation/sphinx-static/theme_overrides.css|   7 +
 Documentation/sphinx/kernel_abi.py | 155 
 scripts/get_abi.pl | 419 +
 29 files changed, 691 insertions(+), 57 deletions(-)
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst
 create mode 100644 Documentation/sphinx/kernel_abi.py
 create mode 100755 scripts/get_abi.pl

-- 
2.9.3


--
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 v2 08/11] scripts/get_abi.pl: avoid use literal blocks when not needed

[Mauro Carvalho Chehab]

The usage of literal blocks make the document very complex,
causing the browser to take a long time to load.

On most ABI descriptions, they're a plain text, and don't
require a literal block.

So, add a logic there with identifies when a literal block
is needed.

As, on literal blocks, we need to respect the original
document space, the most complex part of this patch is
to preserve the original spacing where needed.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/get_abi.pl | 104 +++--
 1 file changed, 78 insertions(+), 26 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ac0f057fa3ca..ba8a7466f896 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -59,29 +59,34 @@ sub parse_abi {
my $ln;
my $has_file;
my $xrefs;
+   my $space;
 
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
while() {
$ln++;
-   if (m/^(\S+):\s*(.*)/i) {
+   if (m/^(\S+)(:\s*)(.*)/i) {
my $new_tag = lc($1);
-   my $content = $2;
+   my $sep = $2;
+   my $content = $3;
 
if (!($new_tag =~ 
m/(what|date|kernelversion|contact|description|users)/)) {
if ($tag eq "description") {
-   $data{$what}->{$tag} .= "\n$content";
-   $data{$what}->{$tag} =~ s/\n+$//;
-   next;
+   # New "tag" is actually part of
+   # description. Don't consider it a tag
+   $new_tag = "";
} else {
parse_error($file, $ln, "tag '$tag' is 
invalid", $_);
}
}
 
if ($new_tag =~ m/what/) {
+   $space = "";
if ($tag =~ m/what/) {
$what .= ", " . $content;
} else {
+   parse_error($file, $ln, "What '$what' 
doesn't have a description", "") if ($what && !$data{$what}->{description});
+
$what = $content;
$new_what = 1;
}
@@ -108,25 +113,38 @@ sub parse_abi {
next;
}
 
-   $tag = $new_tag;
+   if ($new_tag) {
+   $tag = $new_tag;
 
-   if ($new_what) {
-   $new_what = 0;
+   if ($new_what) {
+   $new_what = 0;
 
-   $data{$what}->{type} = $type;
-   $data{$what}->{file} = $name;
-   print STDERR "\twhat: $what\n" if ($debug > 1);
-   }
+   $data{$what}->{type} = $type;
+   $data{$what}->{file} = $name;
+   print STDERR "\twhat: $what\n" if 
($debug > 1);
+   }
 
-   if (!$what) {
-   parse_error($file, $ln, "'What:' should come 
first:", $_);
+   if (!$what) {
+   parse_error($file, $ln, "'What:' should 
come first:", $_);
+   next;
+   }
+   if ($tag eq "description") {
+   next if ($content =~ m/^\s*$/);
+   if ($content =~ m/^(\s*)(.*)/) {
+   my $new_content = $2;
+   $space = $new_tag . $sep . $1;
+   while ($space =~ s/\t+/' ' x 
(length($&) * 8 - length($`) % 8)/e) {}
+   $space =~ s/./ /g;
+   $data{$what}->{$tag} .= 
"$new_content\n";
+   }
+   } else {
+   $data{$what}->{$tag} = $content;
+   }
next;
}
-   $data{$what}->{$tag} = $content;
-   next;
}
 
-   # Store any contents before the database
+   # Store any contents before tags at the database
if 

[PATCH v2 05/11] ABI: better identificate tables

[Mauro Carvalho Chehab]

When parsing via script, it is important to know if the script
should consider a description as a literal block that should
be displayed as-is, or if the description can be considered
as a normal text.

Change descriptions to ensure that the preceding line of a table
ends with a colon. That makes easy to identify the need of a
literal block.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra   | 2 +-
 Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 | 6 +++---
 Documentation/ABI/testing/sysfs-class-led-driver-lm3533   | 8 
 Documentation/ABI/testing/sysfs-class-leds-gt683r | 4 ++--
 Documentation/ABI/testing/sysfs-driver-hid-roccat-kone| 2 +-
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra 
b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
index 16020b31ae64..5d41ebadf15e 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
@@ -5,7 +5,7 @@ Description:It is possible to switch the cpi setting of the 
mouse with the
press of a button.
When read, this file returns the raw number of the actual cpi
setting reported by the mouse. This number has to be further
-   processed to receive the real dpi value.
+   processed to receive the real dpi value:
 
VALUE DPI
1 400
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 
b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
index 77cf7ac949af..c0e0a9ae7b3d 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
@@ -4,7 +4,7 @@ KernelVersion:  3.5
 Contact:   Johan Hovold 
 Description:
Get the ALS output channel used as input in
-   ALS-current-control mode (0, 1), where
+   ALS-current-control mode (0, 1), where:
 
0 - out_current0 (backlight 0)
1 - out_current1 (backlight 1)
@@ -28,7 +28,7 @@ Date: April 2012
 KernelVersion: 3.5
 Contact:   Johan Hovold 
 Description:
-   Set the brightness-mapping mode (0, 1), where
+   Set the brightness-mapping mode (0, 1), where:
 
0 - exponential mode
1 - linear mode
@@ -38,7 +38,7 @@ Date: April 2012
 KernelVersion: 3.5
 Contact:   Johan Hovold 
 Description:
-   Set the PWM-input control mask (5 bits), where
+   Set the PWM-input control mask (5 bits), where:
 
bit 5 - PWM-input enabled in Zone 4
bit 4 - PWM-input enabled in Zone 3
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 
b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
index 620ebb3b9baa..e4c89b261546 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
@@ -4,7 +4,7 @@ KernelVersion:  3.5
 Contact:   Johan Hovold 
 Description:
Set the ALS output channel to use as input in
-   ALS-current-control mode (1, 2), where
+   ALS-current-control mode (1, 2), where:
 
1 - out_current1
2 - out_current2
@@ -22,7 +22,7 @@ Date: April 2012
 KernelVersion: 3.5
 Contact:   Johan Hovold 
 Description:
-   Set the pattern generator fall and rise times (0..7), where
+   Set the pattern generator fall and rise times (0..7), where:
 
0 - 2048 us
1 - 262 ms
@@ -45,7 +45,7 @@ Date: April 2012
 KernelVersion: 3.5
 Contact:   Johan Hovold 
 Description:
-   Set the brightness-mapping mode (0, 1), where
+   Set the brightness-mapping mode (0, 1), where:
 
0 - exponential mode
1 - linear mode
@@ -55,7 +55,7 @@ Date: April 2012
 KernelVersion: 3.5
 Contact:   Johan Hovold 
 Description:
-   Set the PWM-input control mask (5 bits), where
+   Set the PWM-input control mask (5 bits), where:
 
bit 5 - PWM-input enabled in Zone 4
bit 4 - PWM-input enabled in Zone 3
diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r 
b/Documentation/ABI/testing/sysfs-class-leds-gt683r
index e4fae6026e79..6adab27f646e 100644
--- a/Documentation/ABI/testing/sysfs-class-leds-gt683r
+++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r
@@ -5,7 +5,7 @@ Contact:Janne Kanniainen 
 Description:
Set the mode of LEDs. You should 

[PATCH v2 11/11] doc-rst: add ABI documentation to the admin-guide book

[Mauro Carvalho Chehab]

As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.

Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/admin-guide/abi-obsolete.rst |  10 ++
 Documentation/admin-guide/abi-removed.rst  |   4 +
 Documentation/admin-guide/abi-stable.rst   |  13 +++
 Documentation/admin-guide/abi-testing.rst  |  19 
 Documentation/admin-guide/abi.rst  |  11 ++
 Documentation/admin-guide/index.rst|   1 +
 Documentation/conf.py  |   3 +-
 Documentation/sphinx/kernel_abi.py | 155 +
 8 files changed, 215 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst
 create mode 100644 Documentation/sphinx/kernel_abi.py

diff --git a/Documentation/admin-guide/abi-obsolete.rst 
b/Documentation/admin-guide/abi-obsolete.rst
new file mode 100644
index ..cda9168445a5
--- /dev/null
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -0,0 +1,10 @@
+ABI obsolete symbols
+
+
+Documents interfaces that are still remaining in the kernel, but are
+marked to be removed at some later point in time.
+
+The description of the interface will document the reason why it is
+obsolete and when it can be expected to be removed.
+
+.. kernel-abi:: $srctree/Documentation/ABI/obsolete
diff --git a/Documentation/admin-guide/abi-removed.rst 
b/Documentation/admin-guide/abi-removed.rst
new file mode 100644
index ..497978fc9632
--- /dev/null
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -0,0 +1,4 @@
+ABI removed symbols
+===
+
+.. kernel-abi:: $srctree/Documentation/ABI/removed
diff --git a/Documentation/admin-guide/abi-stable.rst 
b/Documentation/admin-guide/abi-stable.rst
new file mode 100644
index ..7495d7a35048
--- /dev/null
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -0,0 +1,13 @@
+ABI stable symbols
+==
+
+Documents the interfaces that the developer has defined to be stable.
+
+Userspace programs are free to use these interfaces with no
+restrictions, and backward compatibility for them will be guaranteed
+for at least 2 years.
+
+Most interfaces (like syscalls) are expected to never change and always
+be available.
+
+.. kernel-abi:: $srctree/Documentation/ABI/stable
diff --git a/Documentation/admin-guide/abi-testing.rst 
b/Documentation/admin-guide/abi-testing.rst
new file mode 100644
index ..5c886fc50b9e
--- /dev/null
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -0,0 +1,19 @@
+ABI testing symbols
+===
+
+Documents interfaces that are felt to be stable,
+as the main development of this interface has been completed.
+
+The interface can be changed to add new features, but the
+current interface will not break by doing this, unless grave
+errors or security problems are found in them.
+
+Userspace programs can start to rely on these interfaces, but they must
+be aware of changes that can occur before these interfaces move to
+be marked stable.
+
+Programs that use these interfaces are strongly encouraged to add their
+name to the description of these interfaces, so that the kernel
+developers can easily notify them if any changes occur.
+
+.. kernel-abi:: $srctree/Documentation/ABI/testing
diff --git a/Documentation/admin-guide/abi.rst 
b/Documentation/admin-guide/abi.rst
new file mode 100644
index ..3b9645c77469
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,11 @@
+=
+Linux ABI description
+=
+
+.. toctree::
+   :maxdepth: 1
+
+   abi-stable
+   abi-testing
+   abi-obsolete
+   abi-removed
diff --git a/Documentation/admin-guide/index.rst 
b/Documentation/admin-guide/index.rst
index 8c60a8a32a1a..da3b10941639 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -16,6 +16,7 @@ etc.
README
kernel-parameters
devices
+   abi
 
 Here is a set of documents aimed at users who are trying to track down
 problems and bugs in particular.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 08aef4595059..a9449875b79a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,8 @@ needs_sphinx = '1.2'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 
'kfigure']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
+ 'kfigure', 'kernel_abi']
 
 # 

[PATCH v2 06/11] scripts: add an script to parse the ABI files

[Mauro Carvalho Chehab]

Add a script to parse the Documentation/ABI files and produce
an output with all entries inside an ABI (sub)directory.

Right now, it outputs its contents on ReST format. It shouldn't
be hard to make it produce other kind of outputs, since the ABI
file parser is implemented in separate than the output generator.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/get_abi.pl | 212 +
 1 file changed, 212 insertions(+)
 create mode 100755 scripts/get_abi.pl

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
new file mode 100755
index ..f7c9944a833c
--- /dev/null
+++ b/scripts/get_abi.pl
@@ -0,0 +1,212 @@
+#!/usr/bin/perl
+
+use strict;
+use Pod::Usage;
+use Getopt::Long;
+use File::Find;
+use Fcntl ':mode';
+
+my $help;
+my $man;
+my $debug;
+
+GetOptions(
+   "debug|d+" => \$debug,
+   'help|?' => \$help,
+   man => \$man
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+pod2usage(2) if (scalar @ARGV != 1);
+
+my ($prefix) = @ARGV;
+
+require Data::Dumper if ($debug);
+
+my %data;
+
+#
+# Displays an error message, printing file name and line
+#
+sub parse_error() {
+   my ($file, $ln, $msg, $data) = @_;
+
+   print STDERR "file $file#$ln: $msg at\n\t$data";
+}
+
+#
+# Parse an ABI file, storing its contents at %data
+#
+sub parse_abi {
+   my $file = $File::Find::name;
+
+   my $mode = (stat($file))[2];
+   return if ($mode & S_IFDIR);
+   return if ($file =~ m,/README,);
+
+   my $name = $file;
+   $name =~ s,.*/,,;
+
+   my $type = $file;
+   $type =~ s,.*/(.*)/.*,$1,;
+
+   my $what;
+   my $new_what;
+   my $tag;
+   my $ln;
+
+   print STDERR "Opening $file\n" if ($debug > 1);
+   open IN, $file;
+   while() {
+   $ln++;
+   if (m/^(\S+):\s*(.*)/i) {
+   my $new_tag = lc($1);
+   my $content = $2;
+
+   if (!($new_tag =~ 
m/(what|date|kernelversion|contact|description|users)/)) {
+   if ($tag eq "description") {
+   $data{$what}->{$tag} .= "\n$content";;
+   $data{$what}->{$tag} =~ s/\n+$//;
+   next;
+   } else {
+   parse_error($file, $ln, "tag '$tag' is 
invalid", $_);
+   }
+   }
+
+   if ($new_tag =~ m/what/) {
+   if ($tag =~ m/what/) {
+   $what .= ", " . $content;
+   } else {
+   $what = $content;
+   $new_what = 1;
+   }
+   $tag = $new_tag;
+   next;
+   }
+
+   $tag = $new_tag;
+
+   if ($new_what) {
+   $new_what = 0;
+
+   $data{$what}->{type} = $type;
+   $data{$what}->{file} = $name;
+   print STDERR "\twhat: $what\n" if ($debug > 1);
+   }
+
+   if (!$what) {
+   parse_error($file, $ln, "'What:' should come 
first:", $_);
+   next;
+   }
+   $data{$what}->{$tag} = $content;
+   next;
+   }
+
+   # Silently ignore any headers before the database
+   next if (!$tag);
+
+   if (m/^\s*(.*)/) {
+   $data{$what}->{$tag} .= "\n$1";
+   $data{$what}->{$tag} =~ s/\n+$//;
+   next;
+   }
+
+   # Everything else is error
+   parse_error($file, $ln, "Unexpected line:", $_);
+   }
+   close IN;
+}
+
+# Outputs the output on ReST format
+sub output_rest {
+   foreach my $what (sort keys %data) {
+   my $type = $data{$what}->{type};
+   my $file = $data{$what}->{file};
+
+   my $w = $what;
+   $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+
+   print "$w\n\n";
+   print "- defined on file $file (type: $type)\n\n::\n\n";
+
+   my $desc = $data{$what}->{description};
+   $desc =~ s/^\s+//;
+
+   # Remove title markups from the description, as they won't work
+   $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
+
+   # put everything inside a code block
+   $desc =~ s/\n/\n /g;
+
+
+   if (!($desc =~ /^\s*$/)) {
+   print " $desc\n\n";
+   } else {
+  

[PATCH v2 07/11] scripts/get_abi.pl: parse files with text at beginning

[Mauro Carvalho Chehab]

It sounds usefult o parse files with has some text at the
beginning. Add support for it.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/get_abi.pl | 59 +-
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index f7c9944a833c..ac0f057fa3ca 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -55,7 +55,10 @@ sub parse_abi {
my $what;
my $new_what;
my $tag;
+   my $label;
my $ln;
+   my $has_file;
+   my $xrefs;
 
print STDERR "Opening $file\n" if ($debug > 1);
open IN, $file;
@@ -67,7 +70,7 @@ sub parse_abi {
 
if (!($new_tag =~ 
m/(what|date|kernelversion|contact|description|users)/)) {
if ($tag eq "description") {
-   $data{$what}->{$tag} .= "\n$content";;
+   $data{$what}->{$tag} .= "\n$content";
$data{$what}->{$tag} =~ s/\n+$//;
next;
} else {
@@ -83,6 +86,25 @@ sub parse_abi {
$new_what = 1;
}
$tag = $new_tag;
+
+   if ($has_file) {
+   $label = "abi_" . $content . " ";
+   $label =~ tr/A-Z/a-z/;
+
+   # Convert special chars to "_"
+   $label =~s/[\x00-\x2f]+/_/g;
+   $label =~s/[\x3a-\x40]+/_/g;
+   $label =~s/[\x7b-\xff]+/_/g;
+   $label =~ s,_+,_,g;
+   $label =~ s,_$,,;
+
+   $data{$what}->{label} .= $label;
+
+   # Escape special chars from content
+   $content 
=~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
+
+   $xrefs .= "- :ref:`$content 
<$label>`\n\n";
+   }
next;
}
 
@@ -104,8 +126,18 @@ sub parse_abi {
next;
}
 
-   # Silently ignore any headers before the database
-   next if (!$tag);
+   # Store any contents before the database
+   if (!$tag) {
+   next if (/^\n/);
+
+   my $my_what = "File $name";
+   $data{$my_what}->{what} = "File $name";
+   $data{$my_what}->{type} = "File";
+   $data{$my_what}->{file} = $name;
+   $data{$my_what}->{description} .= $_;
+   $has_file = 1;
+   next;
+   }
 
if (m/^\s*(.*)/) {
$data{$what}->{$tag} .= "\n$1";
@@ -117,6 +149,11 @@ sub parse_abi {
parse_error($file, $ln, "Unexpected line:", $_);
}
close IN;
+
+   if ($has_file) {
+   my $my_what = "File $name";
+$data{$my_what}->{xrefs} = $xrefs;
+   }
 }
 
 # Outputs the output on ReST format
@@ -128,8 +165,17 @@ sub output_rest {
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
 
+   if ($data{$what}->{label}) {
+   my @labels = split(/\s/, $data{$what}->{label});
+   foreach my $label (@labels) {
+   printf ".. _%s:\n\n", $label;
+   }
+   }
+
print "$w\n\n";
-   print "- defined on file $file (type: $type)\n\n::\n\n";
+
+   print "- defined on file $file (type: $type)\n\n" if ($type ne 
"File");
+   print "::\n\n";
 
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
@@ -144,8 +190,11 @@ sub output_rest {
if (!($desc =~ /^\s*$/)) {
print " $desc\n\n";
} else {
-   print " DESCRIPTION MISSING\n\n";
+   print " DESCRIPTION MISSING for $what\n\n";
}
+
+   printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if 
($data{$what}->{xrefs});
+
}
 }
 
-- 
2.9.3

--
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 v2 10/11] scripts/get_abi.pl: add support for searching for ABI symbols

[Mauro Carvalho Chehab]

Change its syntax to allow switching between ReST output mode
and a new search mode, with allows to seek for ABI symbols
using rejex.

Signed-off-by: Mauro Carvalho Chehab 
---
 scripts/get_abi.pl | 112 -
 1 file changed, 103 insertions(+), 9 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index d437e148b1c0..eb62385630e6 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -9,9 +9,11 @@ use Fcntl ':mode';
 my $help;
 my $man;
 my $debug;
+my $prefix="Documentation/ABI";
 
 GetOptions(
"debug|d+" => \$debug,
+   "dir=s" => \$prefix,
'help|?' => \$help,
man => \$man
 ) or pod2usage(2);
@@ -19,9 +21,12 @@ GetOptions(
 pod2usage(1) if $help;
 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
 
-pod2usage(2) if (scalar @ARGV != 1);
+pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
 
-my ($prefix) = @ARGV;
+my ($cmd, $arg) = @ARGV;
+
+pod2usage(2) if ($cmd ne "search" && $cmd ne "rest");
+pod2usage(2) if ($cmd eq "search" && !$arg);
 
 require Data::Dumper if ($debug);
 
@@ -53,6 +58,7 @@ sub parse_abi {
$data{$nametag}->{what} = "File $name";
$data{$nametag}->{type} = "File";
$data{$nametag}->{file} = $name;
+   $data{$nametag}->{filepath} = $file;
$data{$nametag}->{is_file} = 1;
 
my $type = $file;
@@ -115,6 +121,7 @@ sub parse_abi {
 
$data{$what}->{type} = $type;
$data{$what}->{file} = $name;
+   $data{$what}->{filepath} = $file;
print STDERR "\twhat: $what\n" if 
($debug > 1);
}
 
@@ -183,7 +190,9 @@ sub parse_abi {
close IN;
 }
 
-# Outputs the output on ReST format
+#
+# Outputs the book on ReST format
+#
 sub output_rest {
foreach my $what (sort keys %data) {
my $type = $data{$what}->{type};
@@ -263,6 +272,45 @@ sub output_rest {
 }
 
 #
+# Searches for ABI symbols
+#
+sub search_symbols {
+   foreach my $what (sort keys %data) {
+   next if (!($what =~ m/($arg)/));
+
+   my $type = $data{$what}->{type};
+   next if ($type eq "File");
+
+   my $file = $data{$what}->{filepath};
+
+   my $bar = $what;
+   $bar =~ s/./-/g;
+
+   print "\n$what\n$bar\n\n";
+
+   my $kernelversion = $data{$what}->{kernelversion};
+   my $contact = $data{$what}->{contact};
+   my $users = $data{$what}->{users};
+   my $date = $data{$what}->{date};
+   my $desc = $data{$what}->{description};
+   $kernelversion =~ s/^\s+//;
+   $contact =~ s/^\s+//;
+   $users =~ s/^\s+//;
+   $users =~ s/\n//g;
+   $date =~ s/^\s+//;
+   $desc =~ s/^\s+//;
+
+   printf "Kernel version:\t\t%s\n", $kernelversion if 
($kernelversion);
+   printf "Date:\t\t\t%s\n", $date if ($date);
+   printf "Contact:\t\t%s\n", $contact if ($contact);
+   printf "Users:\t\t\t%s\n", $users if ($users);
+   print "Defined on file:\t$file\n\n";
+   print "Description:\n\n$desc";
+   }
+}
+
+
+#
 # Parses all ABI files located at $prefix dir
 #
 find({wanted =>\_abi, no_chdir => 1}, $prefix);
@@ -270,9 +318,13 @@ find({wanted =>\_abi, no_chdir => 1}, $prefix);
 print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
 
 #
-# Outputs an ReST file with the ABI contents
+# Handles the command
 #
-output_rest
+if ($cmd eq "rest") {
+   output_rest;
+} else {
+   search_symbols;
+}
 
 
 __END__
@@ -283,12 +335,27 @@ abi_book.pl - parse the Linux ABI files and produce a 
ReST book.
 
 =head1 SYNOPSIS
 
-B [--debug] ]
+B [--debug]  []
+
+Where  can be:
+
+=over 8
+
+B [SEARCH_REJEX] - search for [SEARCH_REJEX] inside ABI
+
+B   - output the ABI in ReST markup language
+
+=back
 
 =head1 OPTIONS
 
 =over 8
 
+=item B<--dir>
+
+Changes the location of the ABI search. By default, it uses
+the Documentation/ABI directory.
+
 =item B<--debug>
 
 Put the script in verbose mode, useful for debugging. Can be called multiple
@@ -306,8 +373,35 @@ Prints the manual page and exits.
 
 =head1 DESCRIPTION
 
-Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI)
-and produce a ReST book containing the Linux ABI.
+Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI),
+allowing to search for ABI symbols or to produce a ReST book containing
+the Linux ABI documentation.
+
+=head1 EXAMPLES
+
+Search for all stable symbols with the word "usb":
+
+=over 8
+
+$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable
+
+=back
+
+Search for all symbols that match the rejex expression "usb.*cap":
+
+=over 8
+
+$ scripts/get_abi.pl search 

[PATCH v2 04/11] ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry

[Mauro Carvalho Chehab]

There are two entries for /sys/class/uwb_rc/uwbN//BPST.
The second one has a missing description.

Get rid of it.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/ABI/testing/sysfs-class-uwb_rc | 6 --
 1 file changed, 6 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc 
b/Documentation/ABI/testing/sysfs-class-uwb_rc
index 85f4875d16ac..a0578751c1e3 100644
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc
+++ b/Documentation/ABI/testing/sysfs-class-uwb_rc
@@ -125,12 +125,6 @@ Description:
 The EUI-48 of this device in colon separated hex
 octets.
 
-What:   /sys/class/uwb_rc/uwbN//BPST
-Date:   July 2008
-KernelVersion:  2.6.27
-Contact:linux-...@vger.kernel.org
-Description:
-
 What:   /sys/class/uwb_rc/uwbN//IEs
 Date:   July 2008
 KernelVersion:  2.6.27
-- 
2.9.3

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