[v2,3/5] dt-bindings: Document common property for daisy-chained devices

Message ID f0c3b0c5514f74717c5783360b60062dfe9b8c0f.1507797496.git.lukas@wunner.de
State New
Headers show
Series
  • GPIO driver for Maxim MAX3191x
Related show

Commit Message

Lukas Wunner Oct. 12, 2017, 10:40 a.m.
Many serially-attached GPIO and IIO devices are daisy-chainable.

    Examples for GPIO devices are Maxim MAX3191x and TI SN65HVS88x:
    https://datasheets.maximintegrated.com/en/ds/MAX31913.pdf
    http://www.ti.com/lit/ds/symlink/sn65hvs880.pdf

    Examples for IIO devices are TI DAC128S085 and TI DAC161S055:
    http://www.ti.com/lit/ds/symlink/dac128s085.pdf
    http://www.ti.com/lit/ds/symlink/dac161s055.pdf

We already have drivers for daisy-chainable devices in the tree but
their devicetree bindings are somewhat inconsistent and ill-named:

    The gpio-74x164.c driver uses "registers-number" to convey the
    number of devices in the daisy-chain.  (Sans vendor prefix,
    multiple vendors sell compatible versions of this chip.)

    The gpio-pisosr.c driver takes a different approach and calculates
    the number of devices in the daisy-chain by dividing the common
    "ngpios" property (Documentation/devicetree/bindings/gpio/gpio.txt)
    by 8 (which assumes that each chip has 8 inputs).

Let's standardize on a common "#daisy-chained-devices" property.
That name was chosen because it's the term most frequently used in
datasheets.  (A less frequently used synonym is "cascaded devices".)

Signed-off-by: Lukas Wunner <lukas@wunner.de>
---
Changes v1 -> v2:

- Newly inserted patch.

 .../devicetree/bindings/common-properties.txt      | 26 ++++++++++++++++++++++
 1 file changed, 26 insertions(+)

Comments

Jonathan Cameron Oct. 15, 2017, 11:30 a.m. | #1
On Thu, 12 Oct 2017 12:40:10 +0200
Lukas Wunner <lukas@wunner.de> wrote:

> Many serially-attached GPIO and IIO devices are daisy-chainable.
> 
>     Examples for GPIO devices are Maxim MAX3191x and TI SN65HVS88x:
>     https://datasheets.maximintegrated.com/en/ds/MAX31913.pdf
>     http://www.ti.com/lit/ds/symlink/sn65hvs880.pdf
> 
>     Examples for IIO devices are TI DAC128S085 and TI DAC161S055:
>     http://www.ti.com/lit/ds/symlink/dac128s085.pdf
>     http://www.ti.com/lit/ds/symlink/dac161s055.pdf
> 
> We already have drivers for daisy-chainable devices in the tree but
> their devicetree bindings are somewhat inconsistent and ill-named:
> 
>     The gpio-74x164.c driver uses "registers-number" to convey the
>     number of devices in the daisy-chain.  (Sans vendor prefix,
>     multiple vendors sell compatible versions of this chip.)
> 
>     The gpio-pisosr.c driver takes a different approach and calculates
>     the number of devices in the daisy-chain by dividing the common
>     "ngpios" property (Documentation/devicetree/bindings/gpio/gpio.txt)
>     by 8 (which assumes that each chip has 8 inputs).
> 
> Let's standardize on a common "#daisy-chained-devices" property.
> That name was chosen because it's the term most frequently used in
> datasheets.  (A less frequently used synonym is "cascaded devices".)
> 
> Signed-off-by: Lukas Wunner <lukas@wunner.de>
Makes sense to me.
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> ---
> Changes v1 -> v2:
> 
> - Newly inserted patch.
> 
>  .../devicetree/bindings/common-properties.txt      | 26 ++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/common-properties.txt b/Documentation/devicetree/bindings/common-properties.txt
> index 697714f8d75c..a3448bfa1c82 100644
> --- a/Documentation/devicetree/bindings/common-properties.txt
> +++ b/Documentation/devicetree/bindings/common-properties.txt
> @@ -1,4 +1,8 @@
>  Common properties
> +=================
> +
> +Endianness
> +----------
>  
>  The Devicetree Specification does not define any properties related to hardware
>  byteswapping, but endianness issues show up frequently in porting Linux to
> @@ -58,3 +62,25 @@ dev: dev@40031000 {
>  	      ...
>  	      little-endian;
>  };
> +
> +Daisy-chained devices
> +---------------------
> +
> +Many serially-attached GPIO and IIO devices are daisy-chainable.  To the
> +host controller, a daisy-chain appears as a single device, but the number
> +of inputs and outputs it provides is the sum of inputs and outputs provided
> +by all of its devices.  The driver needs to know how many devices the
> +daisy-chain comprises to determine the amount of data exchanged, how many
> +inputs and outputs to register and so on.
> +
> +Optional properties:
> + - #daisy-chained-devices: Number of devices in the daisy-chain (default is 1).
> +
> +Example:
> +gpio@0 {
> +	      compatible = "name";
> +	      reg = <0>;
> +	      gpio-controller;
> +	      #gpio-cells = <2>;
> +	      #daisy-chained-devices = <3>;
> +};

--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Rob Herring Oct. 17, 2017, 8:32 p.m. | #2
On Thu, Oct 12, 2017 at 12:40:10PM +0200, Lukas Wunner wrote:
> Many serially-attached GPIO and IIO devices are daisy-chainable.
> 
>     Examples for GPIO devices are Maxim MAX3191x and TI SN65HVS88x:
>     https://datasheets.maximintegrated.com/en/ds/MAX31913.pdf
>     http://www.ti.com/lit/ds/symlink/sn65hvs880.pdf
> 
>     Examples for IIO devices are TI DAC128S085 and TI DAC161S055:
>     http://www.ti.com/lit/ds/symlink/dac128s085.pdf
>     http://www.ti.com/lit/ds/symlink/dac161s055.pdf
> 
> We already have drivers for daisy-chainable devices in the tree but
> their devicetree bindings are somewhat inconsistent and ill-named:
> 
>     The gpio-74x164.c driver uses "registers-number" to convey the
>     number of devices in the daisy-chain.  (Sans vendor prefix,
>     multiple vendors sell compatible versions of this chip.)
> 
>     The gpio-pisosr.c driver takes a different approach and calculates
>     the number of devices in the daisy-chain by dividing the common
>     "ngpios" property (Documentation/devicetree/bindings/gpio/gpio.txt)
>     by 8 (which assumes that each chip has 8 inputs).
> 
> Let's standardize on a common "#daisy-chained-devices" property.
> That name was chosen because it's the term most frequently used in
> datasheets.  (A less frequently used synonym is "cascaded devices".)
> 
> Signed-off-by: Lukas Wunner <lukas@wunner.de>
> ---
> Changes v1 -> v2:
> 
> - Newly inserted patch.
> 
>  .../devicetree/bindings/common-properties.txt      | 26 ++++++++++++++++++++++
>  1 file changed, 26 insertions(+)

Acked-by: Rob Herring <robh@kernel.org>

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

Patch

diff --git a/Documentation/devicetree/bindings/common-properties.txt b/Documentation/devicetree/bindings/common-properties.txt
index 697714f8d75c..a3448bfa1c82 100644
--- a/Documentation/devicetree/bindings/common-properties.txt
+++ b/Documentation/devicetree/bindings/common-properties.txt
@@ -1,4 +1,8 @@ 
 Common properties
+=================
+
+Endianness
+----------
 
 The Devicetree Specification does not define any properties related to hardware
 byteswapping, but endianness issues show up frequently in porting Linux to
@@ -58,3 +62,25 @@  dev: dev@40031000 {
 	      ...
 	      little-endian;
 };
+
+Daisy-chained devices
+---------------------
+
+Many serially-attached GPIO and IIO devices are daisy-chainable.  To the
+host controller, a daisy-chain appears as a single device, but the number
+of inputs and outputs it provides is the sum of inputs and outputs provided
+by all of its devices.  The driver needs to know how many devices the
+daisy-chain comprises to determine the amount of data exchanged, how many
+inputs and outputs to register and so on.
+
+Optional properties:
+ - #daisy-chained-devices: Number of devices in the daisy-chain (default is 1).
+
+Example:
+gpio@0 {
+	      compatible = "name";
+	      reg = <0>;
+	      gpio-controller;
+	      #gpio-cells = <2>;
+	      #daisy-chained-devices = <3>;
+};