diff mbox series

[1/2] dt-bindings: spi: Document binding for generic SPI multiplexer

Message ID 20200114233857.25933-2-chris.packham@alliedtelesis.co.nz
State Changes Requested, archived
Headers show
Series SPI bus multiplexing | expand

Checks

Context Check Description
robh/checkpatch success
robh/dt-meta-schema fail build log

Commit Message

Chris Packham Jan. 14, 2020, 11:38 p.m. UTC 
Add binding documentation for the spi-mux driver. This allows a generic
multiplexer to be used to provide access to multiple SPI devices.

Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
---
 .../devicetree/bindings/spi/spi-mux.yaml      | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/spi/spi-mux.yaml

Comments

Rob Herring Jan. 15, 2020, 6:45 p.m. UTC | #1 
On Tue, Jan 14, 2020 at 5:39 PM Chris Packham
<chris.packham@alliedtelesis.co.nz> wrote:
>
> Add binding documentation for the spi-mux driver. This allows a generic
> multiplexer to be used to provide access to multiple SPI devices.
>
> Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> ---
>  .../devicetree/bindings/spi/spi-mux.yaml      | 82 +++++++++++++++++++
>  1 file changed, 82 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/spi/spi-mux.yaml

Be sure to run 'make dt_binding_check'.

>
> diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml
> new file mode 100644
> index 000000000000..1026d03a69c7
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml
> @@ -0,0 +1,82 @@
> +# SPDX-License-Identifier: GPL-2.0

Dual license new bindings please:

(GPL-2.0-only OR BSD-2-Clause)

> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/spi/spi-mux.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic SPI Multiplexer
> +
> +description: |
> +  This binding describes a SPI bus multiplexer to route the SPI chip select
> +  signals. This can be used when you need more devices than the SPI controller
> +  has chip selects available. An example setup is shown in ASCII art; the actual
> +  setting of the multiplexer to a channel needs to be done by a specific SPI mux
> +  driver.
> +
> +        MOSI /--------------------------------+--------+--------+--------\
> +        MISO |/------------------------------+|-------+|-------+|-------\|
> +         SCL ||/----------------------------+||------+||------+||------\||
> +             |||                            |||      |||      |||      |||
> +      +------------+                        |||      |||      |||      |||
> +      | SoC  |||   |                      +-+++-+  +-+++-+  +-+++-+  +-+++-+
> +      |      |||   |                      | dev |  | dev |  | dev |  | dev |
> +      |   +--+++-+ | CS-X  +------+\      +--+--+  +--+--+  +--+--+  +--+--+
> +      |   | SPI  +-|-------+ Mux  |\\   CS-0 |        |        |        |
> +      |   +------+ |       +--+---+\\\-------/   CS-1 |        |        |
> +      |            |          |    \\\----------------/   CS-2 |        |
> +      |   +------+ |          |     \\-------------------------/   CS-3 |
> +      |   | ?    +-|----------/      \----------------------------------/
> +      |   +------+ |
> +      +------------+
> +
> +allOf:
> +  - $ref: "/schemas/spi/spi-controller.yaml#"
> +
> +properties:
> +  compatible:
> +    const: spi-mux
> +
> +  mux-control:
> +    $ref: "/schemas/mux/mux-controller.yaml#"

That file doesn't exist. If it did, it would still be wrong as that
would be the provider side and this is the client.

The correct name is also 'mux-controls'.

You can assume it has a schema already and you just need to define how
many entries it has (maxItems: 1).

> +
> +required:
> +   - compatible
> +   - reg
> +   - spi-max-frequency
> +   - mux-control
> +
> +examples:
> +   - |
> +     mux: mux-controller {
> +       compatible = "gpio-mux";
> +       #mux-control-cells = <0>;
> +
> +       mux-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>;
> +     };
> +
> +     spi {
> +       spi-mux {

spi-mux@0

> +         compatible = "spi-mux";
> +         #address-cells = <1>;
> +         #size-cells = <0>;
> +         reg = <0>;
> +         spi-max-frequency = <100000000>;

I don't think this makes sense here. The mux doesn't really have any
frequency given the clock and data lines aren't routed thru the mux
(though maybe that's possible if some isolation is needed).

> +
> +         mux-control = <&mux>
> +         mux-control-names = "spi";

Not documented. Drop it as it's not all that useful when there's only 1 entry.

> +
> +         spi-flash@0 {
> +           compatible = "jedec,spi-nor";
> +           #address-cells = <1>;
> +           #size-cells = <1>;
> +           reg = <0>;
> +           spi-max-frequency = <40000000>;
> +         };
> +
> +         spi-device@1 {
> +           compatible = "spidev";

Not a valid compatible.

> +           reg = <1>;
> +           spi-max-frequency = <10000000>;
> +         };
> +       };
> +     };
> --
> 2.25.0
>
Chris Packham Jan. 15, 2020, 8:49 p.m. UTC | #2 
Hi Rob,

On Wed, 2020-01-15 at 12:45 -0600, Rob Herring wrote:
> On Tue, Jan 14, 2020 at 5:39 PM Chris Packham
> <chris.packham@alliedtelesis.co.nz> wrote:
> > 
> > Add binding documentation for the spi-mux driver. This allows a
> > generic
> > multiplexer to be used to provide access to multiple SPI devices.
> > 
> > Signed-off-by: Chris Packham <chris.packham@alliedtelesis.co.nz>
> > ---
> >  .../devicetree/bindings/spi/spi-mux.yaml      | 82
> > +++++++++++++++++++
> >  1 file changed, 82 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/spi/spi-
> > mux.yaml
> 
> Be sure to run 'make dt_binding_check'.
> 

Will do.

> > 
> > diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml
> > b/Documentation/devicetree/bindings/spi/spi-mux.yaml
> > new file mode 100644
> > index 000000000000..1026d03a69c7
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml
> > @@ -0,0 +1,82 @@
> > +# SPDX-License-Identifier: GPL-2.0
> 
> Dual license new bindings please:
> 
> (GPL-2.0-only OR BSD-2-Clause)
> 

Done

> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/spi/spi-mux.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Generic SPI Multiplexer
> > +
> > +description: |
> > +  This binding describes a SPI bus multiplexer to route the SPI
> > chip select
> > +  signals. This can be used when you need more devices than the
> > SPI controller
> > +  has chip selects available. An example setup is shown in ASCII
> > art; the actual
> > +  setting of the multiplexer to a channel needs to be done by a
> > specific SPI mux
> > +  driver.
> > +
> > +        MOSI /--------------------------------+--------+--------+-
> > -------\
> > +        MISO |/------------------------------+|-------+|-------+|-
> > ------\|
> > +         SCL ||/----------------------------+||------+||------+||-
> > -----\||
> > +             |||                            |||      |||      ||| 
> >      |||
> > +      +----------
> > --+                        |||      |||      |||      |||
> > +      | SoC  |||   |                      +-+++-+  +-+++-+  +-+++-
> > +  +-+++-+
> > +      |      |||   |                      | dev |  | dev |  | dev
> > |  | dev |
> > +      |   +--+++-+ | CS-X  +------+\      +--+--+  +--+--+  +--+
> > --+  +--+--+
> > +      |   | SPI  +-|-------+ Mux  |\\   CS-0
> > |        |        |        |
> > +      |   +------+ |       +--+---+\\\-------/   CS-1
> > |        |        |
> > +      |            |          |    \\\----------------/   CS-2
> > |        |
> > +      |   +------+ |          |     \\-------------------------
> > /   CS-3 |
> > +      |   | ?    +-|----------/      \--------------------------
> > --------/
> > +      |   +------+ |
> > +      +------------+
> > +
> > +allOf:
> > +  - $ref: "/schemas/spi/spi-controller.yaml#"
> > +
> > +properties:
> > +  compatible:
> > +    const: spi-mux
> > +
> > +  mux-control:
> > +    $ref: "/schemas/mux/mux-controller.yaml#"
> 
> That file doesn't exist. If it did, it would still be wrong as that
> would be the provider side and this is the client.
> 
> The correct name is also 'mux-controls'.
> 
> You can assume it has a schema already and you just need to define
> how
> many entries it has (maxItems: 1).

I might need a little hand holding on this. Should I assume that there
is a separate schema for the consumer? Or leave out the $ref entirely?

> > +
> > +required:
> > +   - compatible
> > +   - reg
> > +   - spi-max-frequency
> > +   - mux-control
> > +
> > +examples:
> > +   - |
> > +     mux: mux-controller {
> > +       compatible = "gpio-mux";
> > +       #mux-control-cells = <0>;
> > +
> > +       mux-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>;
> > +     };
> > +
> > +     spi {
> > +       spi-mux {
> 
> spi-mux@0
> 

Done.

> > +         compatible = "spi-mux";
> > +         #address-cells = <1>;
> > +         #size-cells = <0>;
> > +         reg = <0>;
> > +         spi-max-frequency = <100000000>;
> 
> I don't think this makes sense here. The mux doesn't really have any
> frequency given the clock and data lines aren't routed thru the mux
> (though maybe that's possible if some isolation is needed).
> 

It's needed to satisfy of_spi_parse_dt().To remove it I'd need to add
an escape hatch to allow this property to be omitted for spi-muxes. Or
change it to be a platform device and take the parent spi bus as a
phandle.

> > +
> > +         mux-control = <&mux>
> > +         mux-control-names = "spi";
> 
> Not documented. Drop it as it's not all that useful when there's only
> 1 entry.

Done. Also updated mux-control -> mux-controls

> > +
> > +         spi-flash@0 {
> > +           compatible = "jedec,spi-nor";
> > +           #address-cells = <1>;
> > +           #size-cells = <1>;
> > +           reg = <0>;
> > +           spi-max-frequency = <40000000>;
> > +         };
> > +
> > +         spi-device@1 {
> > +           compatible = "spidev";
> 
> Not a valid compatible.
> 

Picked a different one.

> > +           reg = <1>;
> > +           spi-max-frequency = <10000000>;
> > +         };
> > +       };
> > +     };
> > --
> > 2.25.0
> >
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/spi/spi-mux.yaml b/Documentation/devicetree/bindings/spi/spi-mux.yaml
new file mode 100644
index 000000000000..1026d03a69c7
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/spi-mux.yaml
@@ -0,0 +1,82 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/spi-mux.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic SPI Multiplexer
+
+description: |
+  This binding describes a SPI bus multiplexer to route the SPI chip select
+  signals. This can be used when you need more devices than the SPI controller
+  has chip selects available. An example setup is shown in ASCII art; the actual
+  setting of the multiplexer to a channel needs to be done by a specific SPI mux
+  driver.
+
+        MOSI /--------------------------------+--------+--------+--------\
+        MISO |/------------------------------+|-------+|-------+|-------\|
+         SCL ||/----------------------------+||------+||------+||------\||
+             |||                            |||      |||      |||      |||
+      +------------+                        |||      |||      |||      |||
+      | SoC  |||   |                      +-+++-+  +-+++-+  +-+++-+  +-+++-+
+      |      |||   |                      | dev |  | dev |  | dev |  | dev |
+      |   +--+++-+ | CS-X  +------+\      +--+--+  +--+--+  +--+--+  +--+--+
+      |   | SPI  +-|-------+ Mux  |\\   CS-0 |        |        |        |
+      |   +------+ |       +--+---+\\\-------/   CS-1 |        |        |
+      |            |          |    \\\----------------/   CS-2 |        |
+      |   +------+ |          |     \\-------------------------/   CS-3 |
+      |   | ?    +-|----------/      \----------------------------------/
+      |   +------+ |
+      +------------+
+
+allOf:
+  - $ref: "/schemas/spi/spi-controller.yaml#"
+
+properties:
+  compatible:
+    const: spi-mux
+
+  mux-control:
+    $ref: "/schemas/mux/mux-controller.yaml#"
+
+required:
+   - compatible
+   - reg
+   - spi-max-frequency
+   - mux-control
+
+examples:
+   - |
+     mux: mux-controller {
+       compatible = "gpio-mux";
+       #mux-control-cells = <0>;
+
+       mux-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>;
+     };
+
+     spi {
+       spi-mux {
+         compatible = "spi-mux";
+         #address-cells = <1>;
+         #size-cells = <0>;
+         reg = <0>;
+         spi-max-frequency = <100000000>;
+
+         mux-control = <&mux>
+         mux-control-names = "spi";
+
+         spi-flash@0 {
+           compatible = "jedec,spi-nor";
+           #address-cells = <1>;
+           #size-cells = <1>;
+           reg = <0>;
+           spi-max-frequency = <40000000>;
+         };
+
+         spi-device@1 {
+           compatible = "spidev";
+           reg = <1>;
+           spi-max-frequency = <10000000>;
+         };
+       };
+     };