[v1,02/36] dt-bindings: spi: support non-spi bindings as SPI slaves
diff mbox series

Message ID 20200315134416.16527-3-sam@ravnborg.org
State New
Headers show
Series
  • dt-bindings: display: convert remaning panel bindings to DT Schema
Related show

Commit Message

Sam Ravnborg March 15, 2020, 1:43 p.m. UTC
Independent bindings can be SPI slaves which for example is
the case for several panel bindings.

Move SPI slave properties to spi-slave.yaml so the independent
SPI slave bindings can include spi-slave.yaml rather than
duplicating the properties.

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Rob Herring <robh@kernel.org>
Cc: Mark Brown <broonie@kernel.org>
Cc: linux-spi@vger.kernel.org
---
 .../bindings/spi/spi-controller.yaml          | 63 +-------------
 .../devicetree/bindings/spi/spi-slave.yaml    | 83 +++++++++++++++++++
 2 files changed, 86 insertions(+), 60 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml

Comments

Linus Walleij March 15, 2020, 4:24 p.m. UTC | #1
On Sun, Mar 15, 2020 at 2:44 PM Sam Ravnborg <sam@ravnborg.org> wrote:

> Independent bindings can be SPI slaves which for example is
> the case for several panel bindings.
>
> Move SPI slave properties to spi-slave.yaml so the independent
> SPI slave bindings can include spi-slave.yaml rather than
> duplicating the properties.

To me it seems like you are creating the common SPI slave
bindings? Maybe the commit message should be about that.

> +  reg:
> +    minimum: 0
> +    maximum: 256

255? Or am I wrong?

Apart from that it looks good to me.

Yours,
Linus Walleij
Mark Brown March 16, 2020, 12:02 p.m. UTC | #2
On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:

> Independent bindings can be SPI slaves which for example is
> the case for several panel bindings.

What is an "independent binding"?

Please submit patches using subject lines reflecting the style for the
subsystem, this makes it easier for people to identify relevant patches.
Look at what existing commits in the area you're changing are doing and
make sure your subject lines visually resemble what they're doing.
There's no need to resubmit to fix this alone.
Sam Ravnborg March 16, 2020, 1:28 p.m. UTC | #3
Hi Mark.

On Mon, Mar 16, 2020 at 12:02:41PM +0000, Mark Brown wrote:
> On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:
> 
> > Independent bindings can be SPI slaves which for example is
> > the case for several panel bindings.
> 
> What is an "independent binding"?

For several panels we have device trees that looks like this:

spi {
    #address-cells = <1>;
    #size-cells = <0>;

    panel@0 {
        compatible = "kingdisplay,kd035g6-54nt";
        reg = <0>;

        spi-max-frequency = <3125000>;
        spi-3wire;
        spi-cs-high;
	...


The bindings are child of the spi controller node, but not specified
in the same binding file as the spi controller node.

A lot of bindings repeats the descriptions of (some of) the
pi-slave properties.
To avoid introducing yet another set of redundant and maybe incomplete
SPI slave property descriptions I moved the relevant properties
from spi-controller.yaml to spi-slave.yaml.

So SPI slaves can now reference spi-slave.yaml to get access to
the SPI slave properties - and the copies can be avoided.
Likewise spi-controller.yml now references spi-slave.yaml.

This was the best way I saw it could be done.

This approach is used in several bindings in this patch set.

	Sam
Mark Brown March 16, 2020, 4:35 p.m. UTC | #4
On Mon, Mar 16, 2020 at 02:28:44PM +0100, Sam Ravnborg wrote:
> On Mon, Mar 16, 2020 at 12:02:41PM +0000, Mark Brown wrote:
> > On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:

> > > Independent bindings can be SPI slaves which for example is
> > > the case for several panel bindings.

> > What is an "independent binding"?

> For several panels we have device trees that looks like this:

So what you're trying to do is define a generic class for SPI slaves
which are just normal children of SPI nodes?  I really can't get to
there from your changelog so we need some work there - in particular
"non-spi bindings" is *very* confusing as as far as I can see these are
bindings for SPI devices.

> The bindings are child of the spi controller node, but not specified
> in the same binding file as the spi controller node.

Of course not, this how all buses work isn't it?

> So SPI slaves can now reference spi-slave.yaml to get access to
> the SPI slave properties - and the copies can be avoided.
> Likewise spi-controller.yml now references spi-slave.yaml.

> This was the best way I saw it could be done.

Rob didn't do the binding conversion but he did review it - I'm a bit
surprised that there's issues here?

Also shouldn't there be some constraint that these devices have to be
the child of a SPI controller or something?  Just including a file
doesn't look right for something like class definition.
Sam Ravnborg March 16, 2020, 6:57 p.m. UTC | #5
Hi Mark.

On Mon, Mar 16, 2020 at 04:35:38PM +0000, Mark Brown wrote:
> On Mon, Mar 16, 2020 at 02:28:44PM +0100, Sam Ravnborg wrote:
> > On Mon, Mar 16, 2020 at 12:02:41PM +0000, Mark Brown wrote:
> > > On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:
> 
> > > > Independent bindings can be SPI slaves which for example is
> > > > the case for several panel bindings.
> 
> > > What is an "independent binding"?
> 
> > For several panels we have device trees that looks like this:
> 
> So what you're trying to do is define a generic class for SPI slaves
> which are just normal children of SPI nodes?  I really can't get to
> there from your changelog so we need some work there - in particular
> "non-spi bindings" is *very* confusing as as far as I can see these are
> bindings for SPI devices.
> 
> > The bindings are child of the spi controller node, but not specified
> > in the same binding file as the spi controller node.
> 
> Of course not, this how all buses work isn't it?
> 
> > So SPI slaves can now reference spi-slave.yaml to get access to
> > the SPI slave properties - and the copies can be avoided.
> > Likewise spi-controller.yml now references spi-slave.yaml.
> 
> > This was the best way I saw it could be done.
> 
> Rob didn't do the binding conversion but he did review it - I'm a bit
> surprised that there's issues here?

For panels we have panel-common.yaml that list all the
typical properties used by a panel - so the individual
panel bindings shall not repeat them.
This is also aligned with the principle of re-using properties rather
than inventing new properties all over.

And with a number of bindings describing HW that is SPI slaves
the idea is to do something like we do for panels.

I look forward for Rob's feedback - but as he is on vacation this week
we may have to wait a week for that.

The simple way forward had been to do like we do in many other places
and include a few SPI properties and be done with it.
This is an attempt to do something better.
If there is push-back or a nack, then we can always do like we do in
other places and just duplicate the properties.

> Also shouldn't there be some constraint that these devices have to be
> the child of a SPI controller or something?  Just including a file
> doesn't look right for something like class definition.

It was the best I could come up with - and this patch was called out
for review in the hope there is a better way than this patch.

We have similar examples like:
  - pincfg-node.yaml
  - regulatro.yaml
  - dma-common.yaml

They are not exactly 1:1 to what we do with spi-slave.yaml, but they
served as inspiration.

	Sam
Mark Brown March 16, 2020, 8:14 p.m. UTC | #6
On Mon, Mar 16, 2020 at 07:57:33PM +0100, Sam Ravnborg wrote:

> It was the best I could come up with - and this patch was called out
> for review in the hope there is a better way than this patch.

It definitely seems like a useful thing, just a bit surprised it's not
already there and if this is the best way to do it.

> We have similar examples like:
>   - pincfg-node.yaml
>   - regulatro.yaml

I'm curious what properties your consumers have for regulators - I'd
expect them to just have simple pointers to the regualtors with no
configuration.
Maxime Ripard March 16, 2020, 8:48 p.m. UTC | #7
Hi Sam,

On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:
> Independent bindings can be SPI slaves which for example is
> the case for several panel bindings.
>
> Move SPI slave properties to spi-slave.yaml so the independent
> SPI slave bindings can include spi-slave.yaml rather than
> duplicating the properties.
>
> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
> Cc: Maxime Ripard <maxime.ripard@bootlin.com>
> Cc: Rob Herring <robh@kernel.org>
> Cc: Mark Brown <broonie@kernel.org>
> Cc: linux-spi@vger.kernel.org
> ---
>  .../bindings/spi/spi-controller.yaml          | 63 +-------------
>  .../devicetree/bindings/spi/spi-slave.yaml    | 83 +++++++++++++++++++
>  2 files changed, 86 insertions(+), 60 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml
>
> diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> index 1e0ca6ccf64b..99531c8d10dd 100644
> --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml
> +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> @@ -67,71 +67,14 @@ patternProperties:
>    "^.*@[0-9a-f]+$":
>      type: object
>
> +    allOf:
> +      - $ref: spi-slave.yaml#
> +
>      properties:
>        compatible:
>          description:
>            Compatible of the SPI device.
>
> -      reg:
> -        minimum: 0
> -        maximum: 256
> -        description:
> -          Chip select used by the device.
> -
> -      spi-3wire:
> -        $ref: /schemas/types.yaml#/definitions/flag
> -        description:
> -          The device requires 3-wire mode.
> -
> -      spi-cpha:
> -        $ref: /schemas/types.yaml#/definitions/flag
> -        description:
> -          The device requires shifted clock phase (CPHA) mode.
> -
> -      spi-cpol:
> -        $ref: /schemas/types.yaml#/definitions/flag
> -        description:
> -          The device requires inverse clock polarity (CPOL) mode.
> -
> -      spi-cs-high:
> -        $ref: /schemas/types.yaml#/definitions/flag
> -        description:
> -          The device requires the chip select active high.
> -
> -      spi-lsb-first:
> -        $ref: /schemas/types.yaml#/definitions/flag
> -        description:
> -          The device requires the LSB first mode.
> -
> -      spi-max-frequency:
> -        $ref: /schemas/types.yaml#/definitions/uint32
> -        description:
> -          Maximum SPI clocking speed of the device in Hz.
> -
> -      spi-rx-bus-width:
> -        allOf:
> -          - $ref: /schemas/types.yaml#/definitions/uint32
> -          - enum: [ 1, 2, 4, 8 ]
> -          - default: 1
> -        description:
> -          Bus width to the SPI bus used for MISO.
> -
> -      spi-rx-delay-us:
> -        description:
> -          Delay, in microseconds, after a read transfer.
> -
> -      spi-tx-bus-width:
> -        allOf:
> -          - $ref: /schemas/types.yaml#/definitions/uint32
> -          - enum: [ 1, 2, 4, 8 ]
> -          - default: 1
> -        description:
> -          Bus width to the SPI bus used for MOSI.
> -
> -      spi-tx-delay-us:
> -        description:
> -          Delay, in microseconds, after a write transfer.
> -

I can see what you're trying to do, but you don't really need to.

All the SPI devices will be declared under a spi controller node that
will validate its child nodes (and thus the devices) already.

Doing it this way would actually make all the checks happen twice,
once as part of the SPI controller, once as part of the SPI device
binding, without any good reason.

Maxime
Sam Ravnborg March 16, 2020, 9:43 p.m. UTC | #8
Hi Maxime.

On Mon, Mar 16, 2020 at 09:48:50PM +0100, Maxime Ripard wrote:
> Hi Sam,
> 
> On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:
> > Independent bindings can be SPI slaves which for example is
> > the case for several panel bindings.
> >
> > Move SPI slave properties to spi-slave.yaml so the independent
> > SPI slave bindings can include spi-slave.yaml rather than
> > duplicating the properties.
> >
> > Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
> > Cc: Maxime Ripard <maxime.ripard@bootlin.com>
> > Cc: Rob Herring <robh@kernel.org>
> > Cc: Mark Brown <broonie@kernel.org>
> > Cc: linux-spi@vger.kernel.org
> > ---
> >  .../bindings/spi/spi-controller.yaml          | 63 +-------------
> >  .../devicetree/bindings/spi/spi-slave.yaml    | 83 +++++++++++++++++++
> >  2 files changed, 86 insertions(+), 60 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > index 1e0ca6ccf64b..99531c8d10dd 100644
> > --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > @@ -67,71 +67,14 @@ patternProperties:
> >    "^.*@[0-9a-f]+$":
> >      type: object
> >
> > +    allOf:
> > +      - $ref: spi-slave.yaml#
> > +
> >      properties:
> >        compatible:
> >          description:
> >            Compatible of the SPI device.
> >
> > -      reg:
> > -        minimum: 0
> > -        maximum: 256
> > -        description:
> > -          Chip select used by the device.
> > -
> > -      spi-3wire:
> > -        $ref: /schemas/types.yaml#/definitions/flag
> > -        description:
> > -          The device requires 3-wire mode.
> > -
> > -      spi-cpha:
> > -        $ref: /schemas/types.yaml#/definitions/flag
> > -        description:
> > -          The device requires shifted clock phase (CPHA) mode.
> > -
> > -      spi-cpol:
> > -        $ref: /schemas/types.yaml#/definitions/flag
> > -        description:
> > -          The device requires inverse clock polarity (CPOL) mode.
> > -
> > -      spi-cs-high:
> > -        $ref: /schemas/types.yaml#/definitions/flag
> > -        description:
> > -          The device requires the chip select active high.
> > -
> > -      spi-lsb-first:
> > -        $ref: /schemas/types.yaml#/definitions/flag
> > -        description:
> > -          The device requires the LSB first mode.
> > -
> > -      spi-max-frequency:
> > -        $ref: /schemas/types.yaml#/definitions/uint32
> > -        description:
> > -          Maximum SPI clocking speed of the device in Hz.
> > -
> > -      spi-rx-bus-width:
> > -        allOf:
> > -          - $ref: /schemas/types.yaml#/definitions/uint32
> > -          - enum: [ 1, 2, 4, 8 ]
> > -          - default: 1
> > -        description:
> > -          Bus width to the SPI bus used for MISO.
> > -
> > -      spi-rx-delay-us:
> > -        description:
> > -          Delay, in microseconds, after a read transfer.
> > -
> > -      spi-tx-bus-width:
> > -        allOf:
> > -          - $ref: /schemas/types.yaml#/definitions/uint32
> > -          - enum: [ 1, 2, 4, 8 ]
> > -          - default: 1
> > -        description:
> > -          Bus width to the SPI bus used for MOSI.
> > -
> > -      spi-tx-delay-us:
> > -        description:
> > -          Delay, in microseconds, after a write transfer.
> > -
> 
> I can see what you're trying to do, but you don't really need to.
> 
> All the SPI devices will be declared under a spi controller node that
> will validate its child nodes (and thus the devices) already.

This was the missing piece - thanks.
And as Mark put it "why is this suddenly an issue"?
Turns out this is already properly handled and I made up an issue.
Maybe Mark tried to explian it to me already...

> 
> Doing it this way would actually make all the checks happen twice,
> once as part of the SPI controller, once as part of the SPI device
> binding, without any good reason.

I had focus on validating the example in the binding
file and not the full picture.

One thing I do not see properly addressed, but maybe I just miss it.
What triggers that we catch properties that are not supposed to be
present?

If we see a unsupported property "foobar":

spi {
    ...
    panel {
       ....
       foobar = <1>;
    };
};

somewhere in a SPI slave binding we should catch this.
If for no other reasons that it could be a simple spelling mistake
that otherwise could go undetected for a long time.
But maybe this is really not feasible to do?

	Sam
Maxime Ripard March 17, 2020, 9:02 a.m. UTC | #9
Hi,

On Mon, Mar 16, 2020 at 10:43:46PM +0100, Sam Ravnborg wrote:
> On Mon, Mar 16, 2020 at 09:48:50PM +0100, Maxime Ripard wrote:
> > Hi Sam,
> >
> > On Sun, Mar 15, 2020 at 02:43:42PM +0100, Sam Ravnborg wrote:
> > > Independent bindings can be SPI slaves which for example is
> > > the case for several panel bindings.
> > >
> > > Move SPI slave properties to spi-slave.yaml so the independent
> > > SPI slave bindings can include spi-slave.yaml rather than
> > > duplicating the properties.
> > >
> > > Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
> > > Cc: Maxime Ripard <maxime.ripard@bootlin.com>
> > > Cc: Rob Herring <robh@kernel.org>
> > > Cc: Mark Brown <broonie@kernel.org>
> > > Cc: linux-spi@vger.kernel.org
> > > ---
> > >  .../bindings/spi/spi-controller.yaml          | 63 +-------------
> > >  .../devicetree/bindings/spi/spi-slave.yaml    | 83 +++++++++++++++++++
> > >  2 files changed, 86 insertions(+), 60 deletions(-)
> > >  create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > > index 1e0ca6ccf64b..99531c8d10dd 100644
> > > --- a/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > > +++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml
> > > @@ -67,71 +67,14 @@ patternProperties:
> > >    "^.*@[0-9a-f]+$":
> > >      type: object
> > >
> > > +    allOf:
> > > +      - $ref: spi-slave.yaml#
> > > +
> > >      properties:
> > >        compatible:
> > >          description:
> > >            Compatible of the SPI device.
> > >
> > > -      reg:
> > > -        minimum: 0
> > > -        maximum: 256
> > > -        description:
> > > -          Chip select used by the device.
> > > -
> > > -      spi-3wire:
> > > -        $ref: /schemas/types.yaml#/definitions/flag
> > > -        description:
> > > -          The device requires 3-wire mode.
> > > -
> > > -      spi-cpha:
> > > -        $ref: /schemas/types.yaml#/definitions/flag
> > > -        description:
> > > -          The device requires shifted clock phase (CPHA) mode.
> > > -
> > > -      spi-cpol:
> > > -        $ref: /schemas/types.yaml#/definitions/flag
> > > -        description:
> > > -          The device requires inverse clock polarity (CPOL) mode.
> > > -
> > > -      spi-cs-high:
> > > -        $ref: /schemas/types.yaml#/definitions/flag
> > > -        description:
> > > -          The device requires the chip select active high.
> > > -
> > > -      spi-lsb-first:
> > > -        $ref: /schemas/types.yaml#/definitions/flag
> > > -        description:
> > > -          The device requires the LSB first mode.
> > > -
> > > -      spi-max-frequency:
> > > -        $ref: /schemas/types.yaml#/definitions/uint32
> > > -        description:
> > > -          Maximum SPI clocking speed of the device in Hz.
> > > -
> > > -      spi-rx-bus-width:
> > > -        allOf:
> > > -          - $ref: /schemas/types.yaml#/definitions/uint32
> > > -          - enum: [ 1, 2, 4, 8 ]
> > > -          - default: 1
> > > -        description:
> > > -          Bus width to the SPI bus used for MISO.
> > > -
> > > -      spi-rx-delay-us:
> > > -        description:
> > > -          Delay, in microseconds, after a read transfer.
> > > -
> > > -      spi-tx-bus-width:
> > > -        allOf:
> > > -          - $ref: /schemas/types.yaml#/definitions/uint32
> > > -          - enum: [ 1, 2, 4, 8 ]
> > > -          - default: 1
> > > -        description:
> > > -          Bus width to the SPI bus used for MOSI.
> > > -
> > > -      spi-tx-delay-us:
> > > -        description:
> > > -          Delay, in microseconds, after a write transfer.
> > > -
> >
> > I can see what you're trying to do, but you don't really need to.
> >
> > All the SPI devices will be declared under a spi controller node that
> > will validate its child nodes (and thus the devices) already.
>
> This was the missing piece - thanks.
> And as Mark put it "why is this suddenly an issue"?
> Turns out this is already properly handled and I made up an issue.
> Maybe Mark tried to explian it to me already...

Yeah, the schemas multi-layering thing is pretty difficult to get used
to :)

> >
> > Doing it this way would actually make all the checks happen twice,
> > once as part of the SPI controller, once as part of the SPI device
> > binding, without any good reason.
>
> I had focus on validating the example in the binding
> file and not the full picture.
>
> One thing I do not see properly addressed, but maybe I just miss it.
> What triggers that we catch properties that are not supposed to be
> present?
>
> If we see a unsupported property "foobar":
>
> spi {
>     ...
>     panel {
>        ....
>        foobar = <1>;
>     };
> };
>
> somewhere in a SPI slave binding we should catch this.
> If for no other reasons that it could be a simple spelling mistake
> that otherwise could go undetected for a long time.
> But maybe this is really not feasible to do?

So you have multiple things here you can do.

Like I said, the schemas are all run as some kind of layers, and each
schema must validate, so you'll want to make a schema that will
validate only what's it supposed to be validating.

Let's use your SPI panel as an example. The SPI controller schema has
a description of what a controller is supposed to look like, and the
properties that are useful to that controller in the devices (things
like the chip-select number, phase settings, etc).

However, at the controller level, you have no idea what devices are
connected, and thus you cannot limit the number of properties a child
is going to have.

The second layer that comes in is the device binding itself. Here,
you'll know what the device itself needs, but you don't really care
about the SPI controller setting itself, since you could have pretty
much each combination in various DTs.

The main property to restrict the allowed properties is
additionalProperties, and setting it to false will raise an error for
each property encountered that isn't part of the *current*
schema. This means that we can't set it for the spi controller
binding, and we would need to duplicate the list of all the generic
SPI properties in each and every binding to avoid spurious error
messages: this is not really ideal, but some (early) schemas are doing
this.

The next spec of the schema language introduces a new property though
that is unevaluatedProperties, which works pretty much like
additionalProperties, but will emit an error only if no schema defines
it. Like I said, the library implementing the schema validation logic
doesn't implement that new spec yet, but the tools allow that property
to be set (but it's ignored). It would be best to simply use
unevaluatedProperties in your panel patch, and when the tools will be
updated you'll get the behaviour you want.

Maxime
Mark Brown March 17, 2020, 11:39 a.m. UTC | #10
On Mon, Mar 16, 2020 at 10:43:46PM +0100, Sam Ravnborg wrote:
> On Mon, Mar 16, 2020 at 09:48:50PM +0100, Maxime Ripard wrote:

> > All the SPI devices will be declared under a spi controller node that
> > will validate its child nodes (and thus the devices) already.

> This was the missing piece - thanks.
> And as Mark put it "why is this suddenly an issue"?
> Turns out this is already properly handled and I made up an issue.
> Maybe Mark tried to explian it to me already...

No, I didn't actually understand how it worked - I was just pretty sure
that it should and trusted that Rob and Maxime had got it right.

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/spi/spi-controller.yaml b/Documentation/devicetree/bindings/spi/spi-controller.yaml
index 1e0ca6ccf64b..99531c8d10dd 100644
--- a/Documentation/devicetree/bindings/spi/spi-controller.yaml
+++ b/Documentation/devicetree/bindings/spi/spi-controller.yaml
@@ -67,71 +67,14 @@  patternProperties:
   "^.*@[0-9a-f]+$":
     type: object
 
+    allOf:
+      - $ref: spi-slave.yaml#
+
     properties:
       compatible:
         description:
           Compatible of the SPI device.
 
-      reg:
-        minimum: 0
-        maximum: 256
-        description:
-          Chip select used by the device.
-
-      spi-3wire:
-        $ref: /schemas/types.yaml#/definitions/flag
-        description:
-          The device requires 3-wire mode.
-
-      spi-cpha:
-        $ref: /schemas/types.yaml#/definitions/flag
-        description:
-          The device requires shifted clock phase (CPHA) mode.
-
-      spi-cpol:
-        $ref: /schemas/types.yaml#/definitions/flag
-        description:
-          The device requires inverse clock polarity (CPOL) mode.
-
-      spi-cs-high:
-        $ref: /schemas/types.yaml#/definitions/flag
-        description:
-          The device requires the chip select active high.
-
-      spi-lsb-first:
-        $ref: /schemas/types.yaml#/definitions/flag
-        description:
-          The device requires the LSB first mode.
-
-      spi-max-frequency:
-        $ref: /schemas/types.yaml#/definitions/uint32
-        description:
-          Maximum SPI clocking speed of the device in Hz.
-
-      spi-rx-bus-width:
-        allOf:
-          - $ref: /schemas/types.yaml#/definitions/uint32
-          - enum: [ 1, 2, 4, 8 ]
-          - default: 1
-        description:
-          Bus width to the SPI bus used for MISO.
-
-      spi-rx-delay-us:
-        description:
-          Delay, in microseconds, after a read transfer.
-
-      spi-tx-bus-width:
-        allOf:
-          - $ref: /schemas/types.yaml#/definitions/uint32
-          - enum: [ 1, 2, 4, 8 ]
-          - default: 1
-        description:
-          Bus width to the SPI bus used for MOSI.
-
-      spi-tx-delay-us:
-        description:
-          Delay, in microseconds, after a write transfer.
-
     required:
       - compatible
       - reg
diff --git a/Documentation/devicetree/bindings/spi/spi-slave.yaml b/Documentation/devicetree/bindings/spi/spi-slave.yaml
new file mode 100644
index 000000000000..fa50d9dfab41
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/spi-slave.yaml
@@ -0,0 +1,83 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/spi-slave.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: SPI slave generic binding
+
+maintainers:
+  - Mark Brown <broonie@kernel.org>
+
+description: |
+  This document defines device tree properties common to SPI slaves.
+  It doesn't constitue a device tree binding specification by
+  itself but is meant to be referenced by device tree bindings.
+
+  When referenced from device tree bindings the properties defined in this
+  document are defined as follows. The device tree bindings are responsible
+  for defining whether each property is required or optional.
+
+properties:
+
+  reg:
+    minimum: 0
+    maximum: 256
+    description:
+      Chip select used by the device.
+
+  spi-3wire:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The device requires 3-wire mode.
+
+  spi-cpha:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The device requires shifted clock phase (CPHA) mode.
+
+  spi-cpol:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The device requires inverse clock polarity (CPOL) mode.
+
+  spi-cs-high:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The device requires the chip select active high.
+
+  spi-lsb-first:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description:
+      The device requires the LSB first mode.
+
+  spi-max-frequency:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      Maximum SPI clocking speed of the device in Hz.
+
+  spi-rx-bus-width:
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32
+      - enum: [ 1, 2, 4, 8 ]
+      - default: 1
+    description:
+      Bus width to the SPI bus used for MISO.
+
+  spi-rx-delay-us:
+    description:
+      Delay, in microseconds, after a read transfer.
+
+  spi-tx-bus-width:
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32
+      - enum: [ 1, 2, 4, 8 ]
+      - default: 1
+    description:
+      Bus width to the SPI bus used for MOSI.
+
+  spi-tx-delay-us:
+    description:
+      Delay, in microseconds, after a write transfer.
+
+...