Skip to contentSkip to conversation

Add bindings for peripheral-specific SPI controller properties

PATCH In review Pratyush Yadav 3 participants 11 messages Nov 9, 2021 – Dec 1, 2021

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

v3 cover Add bindings for peripheral-specific SPI controller properties

Hi,

This series adds bindings for peripheral-specific SPI controller properties. See patch 1 for more info on the motivations behind this.

This is the best approach that I came up with with my limited knowledge of JSON schema. It has some limitations that are mentioned in patch 1. I don't know of any better ways to model this. Suggestions are welcome!

Changes in v3:
- s/slave/peripheral/g
- Drop the | on description.
- Drop the compatible property.

Changes in v2:
- Move other subnode properties listed in spi-controller.yaml to spi-slave-props.yaml
- Move the Cadence controller-specific properties out of spi-slave-props.yaml. They will be added in a separate file.
- Add a reference to spi-slave-props.yaml in spi-controller.yaml.
- Update description.

Pratyush Yadav (3):
spi: dt-bindings: add schema listing peripheral-specific properties
spi: dt-bindings: cdns,qspi-nor: Move peripheral-specific properties
out
dt-bindings: mtd: spi-nor: Add a reference to
spi-peripheral-props.yaml

 .../bindings/mtd/jedec,spi-nor.yaml           |  3 +-
 .../spi/cdns,qspi-nor-peripheral-props.yaml   | 42 +++++++++
 .../bindings/spi/cdns,qspi-nor.yaml           | 33 -------
 .../bindings/spi/spi-controller.yaml          | 69 +-------------
 .../bindings/spi/spi-peripheral-props.yaml    | 89 +++++++++++++++++++
 5 files changed, 135 insertions(+), 101 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml
 create mode 100644 Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml

--
2.33.1.835.ge9e5ba39a7

#1 lore raw

PATCH v3 1/3 spi: dt-bindings: add schema listing peripheral-specific properties

Many SPI controllers need to add properties to peripheral devices. This could be the delay in clock or data lines, etc. These properties are controller specific but need to be defined in the peripheral node because they are per-peripheral and there can be multiple peripherals attached to a controller.

If these properties are not added to the peripheral binding, then the dtbs check emits a warning. But these properties do not make much sense in the peripheral binding because they are controller-specific and they will just pollute every peripheral binding. So this binding is added to collect all such properties from all such controllers. Peripheral bindings should simply refer to this binding and they should be rid of the warnings.

There are some limitations with this approach. Firstly, there is no way to specify required properties. The schema contains properties for all controllers and there is no way to know which controller is being used. Secondly, there is no way to restrict additional properties. Since this schema will be used with an allOf operator, additionalProperties needs to be true. In addition, the peripheral schema will have to set
unevaluatedProperties: false.

Despite these limitations, this appears to be the best solution to this problem that doesn't involve modifying existing tools or schema specs.

---

Changes in v3:
- s/slave/peripheral/g
- Drop the | on description.
- Drop the compatible property.

Changes in v2:
- Move other subnode properties listed in spi-controller.yaml to spi-slave-props.yaml
- Move the Cadence controller-specific properties out of spi-slave-props.yaml. They will be added in a separate file.
- Add a reference to spi-slave-props.yaml in spi-controller.yaml.
- Update description.

 .../bindings/spi/spi-controller.yaml          | 69 +--------------
 .../bindings/spi/spi-peripheral-props.yaml    | 87 +++++++++++++++++++
 2 files changed, 89 insertions(+), 67 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml
Documentation/devicetree/bindings/spi/spi-controller.yaml +2 -67
index 8246891602e7..36b72518f565 100644
@@ -94,73 +94,8 @@ patternProperties:
   "^.*@[0-9a-f]+$":
     type: object
 
-    properties:
-      compatible:
-        description:
-          Compatible of the SPI device.
-
-      reg:
-        minItems: 1
-        maxItems: 256
-        items:
-          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:
-        description:
-          Bus width to the SPI bus used for read transfers.
-          If 0 is provided, then no RX will be possible on this device.
-        $ref: /schemas/types.yaml#/definitions/uint32
-        enum: [0, 1, 2, 4, 8]
-        default: 1
-
-      spi-rx-delay-us:
-        description:
-          Delay, in microseconds, after a read transfer.
-
-      spi-tx-bus-width:
-        description:
-          Bus width to the SPI bus used for write transfers.
-          If 0 is provided, then no TX will be possible on this device.
-        $ref: /schemas/types.yaml#/definitions/uint32
-        enum: [0, 1, 2, 4, 8]
-        default: 1
-
-      spi-tx-delay-us:
-        description:
-          Delay, in microseconds, after a write transfer.
+    allOf:
+      - $ref: spi-peripheral-props.yaml
 
     required:
       - compatible
Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml new file +87 -0

87 lines not on this page · raw message

Signature · 1 line
2.33.1.835.ge9e5ba39a7
maintainer Reviewed-by on v3 1/3
#2 lore raw

Re: [PATCH v3 1/3] spi: dt-bindings: add schema listing peripheral-specific properties

Quoted 42 lines · Pratyush Yadav

Many SPI controllers need to add properties to peripheral devices. This could be the delay in clock or data lines, etc. These properties are controller specific but need to be defined in the peripheral node because they are per-peripheral and there can be multiple peripherals attached to a controller.

If these properties are not added to the peripheral binding, then the dtbs check emits a warning. But these properties do not make much sense in the peripheral binding because they are controller-specific and they will just pollute every peripheral binding. So this binding is added to collect all such properties from all such controllers. Peripheral bindings should simply refer to this binding and they should be rid of the warnings.

There are some limitations with this approach. Firstly, there is no way to specify required properties. The schema contains properties for all controllers and there is no way to know which controller is being used. Secondly, there is no way to restrict additional properties. Since this schema will be used with an allOf operator, additionalProperties needs to be true. In addition, the peripheral schema will have to set
unevaluatedProperties: false.

Despite these limitations, this appears to be the best solution to this problem that doesn't involve modifying existing tools or schema specs.

---

Changes in v3:
- s/slave/peripheral/g
- Drop the | on description.
- Drop the compatible property.

Changes in v2:
- Move other subnode properties listed in spi-controller.yaml to spi-slave-props.yaml
- Move the Cadence controller-specific properties out of spi-slave-props.yaml. They will be added in a separate file.
- Add a reference to spi-slave-props.yaml in spi-controller.yaml.
- Update description.

Quoted 4 lines
 .../bindings/spi/spi-controller.yaml          | 69 +--------------
 .../bindings/spi/spi-peripheral-props.yaml    | 87 +++++++++++++++++++
 2 files changed, 89 insertions(+), 67 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml
#3 lore raw

PATCH v3 2/3 spi: dt-bindings: cdns,qspi-nor: Move peripheral-specific properties out

In reply to Pratyush Yadav

The spi-peripheral-props.yaml schema contains peripheral-specific properties for SPI controllers that should be present in the peripheral node. Move peripheral-specific properties to a separate file and refer to it in spi-peripheral-props.yaml.

---

Changes in v3:
- s/slave/peripheral/g

Changes in v2:
- New in v2.

 .../spi/cdns,qspi-nor-peripheral-props.yaml   | 42 +++++++++++++++++++
 .../bindings/spi/cdns,qspi-nor.yaml           | 33 ---------------
 .../bindings/spi/spi-peripheral-props.yaml    |  2 +
 3 files changed, 44 insertions(+), 33 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml
Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml new file +42 -0
new file mode 100644
index 000000000000..553601a441a7
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/cdns,qspi-nor-peripheral-props.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Peripheral-specific properties for the Cadence QSPI controller.
+
+description:
+  See spi-peripheral-props.yaml for more info.
+
+maintainers:
+  - Pratyush Yadav <[email protected]>
+
+properties:
+  # cdns,qspi-nor.yaml
+  cdns,read-delay:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      Delay for read capture logic, in clock cycles.
+
+  cdns,tshsl-ns:
+    description:
+      Delay in nanoseconds for the length that the master mode chip select
+      outputs are de-asserted between transactions.
+
+  cdns,tsd2d-ns:
+    description:
+      Delay in nanoseconds between one chip select being de-activated
+      and the activation of another.
+
+  cdns,tchsh-ns:
+    description:
+      Delay in nanoseconds between last bit of current transaction and
+      deasserting the device chip select (qspi_n_ss_out).
+
+  cdns,tslch-ns:
+    description:
+      Delay in nanoseconds between setting qspi_n_ss_out low and
+      first bit transfer.
+
+additionalProperties: true
Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml +0 -33
index ca155abbda7a..a439e3ed753f 100644
@@ -86,39 +86,6 @@ properties:
     items:
       enum: [ qspi, qspi-ocp ]
 
-# subnode's properties
-patternProperties:
-  "@[0-9a-f]+$":
-    type: object
-    description:
-      Flash device uses the below defined properties in the subnode.
-
-    properties:
-      cdns,read-delay:
-        $ref: /schemas/types.yaml#/definitions/uint32
-        description:
-          Delay for read capture logic, in clock cycles.
-
-      cdns,tshsl-ns:
-        description:
-          Delay in nanoseconds for the length that the master mode chip select
-          outputs are de-asserted between transactions.
-
-      cdns,tsd2d-ns:
-        description:
-          Delay in nanoseconds between one chip select being de-activated
-          and the activation of another.
-
-      cdns,tchsh-ns:
-        description:
-          Delay in nanoseconds between last bit of current transaction and
-          deasserting the device chip select (qspi_n_ss_out).
-
-      cdns,tslch-ns:
-        description:
-          Delay in nanoseconds between setting qspi_n_ss_out low and
-          first bit transfer.
-
 required:
   - compatible
   - reg
Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +2 -0
index 105fa2840e72..5dd209206e88 100644
@@ -83,5 +83,7 @@ properties:
       Delay, in microseconds, after a write transfer.
 
 # The controller specific properties go here.
+allOf:
+  - $ref: cdns,qspi-nor-peripheral-props.yaml#
 
 additionalProperties: true
Signature · 1 line
2.33.1.835.ge9e5ba39a7
maintainer Reviewed-by on v3 2/3
#4 lore raw

Re: [PATCH v3 2/3] spi: dt-bindings: cdns,qspi-nor: Move peripheral-specific properties out

Quoted 12 lines · Pratyush Yadav

The spi-peripheral-props.yaml schema contains peripheral-specific properties for SPI controllers that should be present in the peripheral node. Move peripheral-specific properties to a separate file and refer to it in spi-peripheral-props.yaml.

---

Changes in v3:
- s/slave/peripheral/g

Quoted 8 lines

Changes in v2:
- New in v2.

 .../spi/cdns,qspi-nor-peripheral-props.yaml   | 42 +++++++++++++++++++
 .../bindings/spi/cdns,qspi-nor.yaml           | 33 ---------------
 .../bindings/spi/spi-peripheral-props.yaml    |  2 +
 3 files changed, 44 insertions(+), 33 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml
#5 lore raw

PATCH v3 3/3 dt-bindings: mtd: spi-nor: Add a reference to spi-peripheral-props.yaml

In reply to Pratyush Yadav

The spi-peripheral-props.yaml schema contains peripheral-specific properties for SPI controllers that should be present in the peripheral node. Add a reference to that so its constraints are followed.

additionalProperties: false cannot be used since it marks the controller properties as unknown. Use unevaluatedProperties: false instead. This has the side effect of allowing extra properties that are not specified in the schema. The alternative is to list all the controller properties in this schema but that would mean every peripheral binding would have to repeat the same set of properties for each controller.

---

Changes in v3:
- s/slave/peripheral/g

 Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml +2 -1
index ed590d7c6e37..39421f7233e4 100644
@@ -11,6 +11,7 @@ maintainers:
 
 allOf:
   - $ref: "mtd.yaml#"
+  - $ref: /schemas/spi/spi-peripheral-props.yaml#
 
 properties:
   compatible:
@@ -88,7 +89,7 @@ patternProperties:
   "^otp(-[0-9]+)?$":
     type: object
 
-additionalProperties: false
+unevaluatedProperties: false
 
 examples:
   - |
Signature · 1 line
2.33.1.835.ge9e5ba39a7
maintainer Reviewed-by on v3 3/3
#6 lore raw

Re: [PATCH v3 3/3] dt-bindings: mtd: spi-nor: Add a reference to spi-peripheral-props.yaml

Quoted 13 lines · Pratyush Yadav

The spi-peripheral-props.yaml schema contains peripheral-specific properties for SPI controllers that should be present in the peripheral node. Add a reference to that so its constraints are followed.

additionalProperties: false cannot be used since it marks the controller properties as unknown. Use unevaluatedProperties: false instead. This has the side effect of allowing extra properties that are not specified in the schema. The alternative is to list all the controller properties in this schema but that would mean every peripheral binding would have to repeat the same set of properties for each controller.

Quoted 7 lines

---

Changes in v3:
- s/slave/peripheral/g

 Documentation/devicetree/bindings/mtd/jedec,spi-nor.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
#7 lore raw
In reply to Pratyush Yadav

Hi Rob,

Quoted 8 lines · Pratyush Yadav

Hi,

This series adds bindings for peripheral-specific SPI controller properties. See patch 1 for more info on the motivations behind this.

This is the best approach that I came up with with my limited knowledge of JSON schema. It has some limitations that are mentioned in patch 1. I don't know of any better ways to model this. Suggestions are welcome!

Do you plan to take this series through your tree or should I poke Mark about it?

Quoted 33 lines

Changes in v3:
- s/slave/peripheral/g
- Drop the | on description.
- Drop the compatible property.

Changes in v2:
- Move other subnode properties listed in spi-controller.yaml to spi-slave-props.yaml
- Move the Cadence controller-specific properties out of spi-slave-props.yaml. They will be added in a separate file.
- Add a reference to spi-slave-props.yaml in spi-controller.yaml.
- Update description.

Pratyush Yadav (3):
spi: dt-bindings: add schema listing peripheral-specific properties
spi: dt-bindings: cdns,qspi-nor: Move peripheral-specific properties
out
dt-bindings: mtd: spi-nor: Add a reference to
spi-peripheral-props.yaml

 .../bindings/mtd/jedec,spi-nor.yaml           |  3 +-
 .../spi/cdns,qspi-nor-peripheral-props.yaml   | 42 +++++++++
 .../bindings/spi/cdns,qspi-nor.yaml           | 33 -------
 .../bindings/spi/spi-controller.yaml          | 69 +-------------
 .../bindings/spi/spi-peripheral-props.yaml    | 89 +++++++++++++++++++
 5 files changed, 135 insertions(+), 101 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/spi/cdns,qspi-nor-peripheral-props.yaml
 create mode 100644 Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml

--
2.33.1.835.ge9e5ba39a7

Signature · 7 lines
Regards,
Pratyush Yadav
Texas Instruments Inc.

______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/
maintainer
#8 lore raw
Quoted 8 lines · Pratyush Yadav
Quoted 3 lines · Pratyush Yadav

This is the best approach that I came up with with my limited knowledge of JSON schema. It has some limitations that are mentioned in patch 1. I don't know of any better ways to model this. Suggestions are welcome!

Do you plan to take this series through your tree or should I poke Mark about it?

I'd expect to take it through my tree but please allow a reasonable time for reviews...

______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/

#9 lore raw
Quoted 7 lines · Mark Brown
Quoted 5 lines · Pratyush Yadav
Quoted 3 lines · Pratyush Yadav

This is the best approach that I came up with with my limited knowledge of JSON schema. It has some limitations that are mentioned in patch 1. I don't know of any better ways to model this. Suggestions are welcome!

Quoted 5 lines
Quoted 2 lines

Do you plan to take this series through your tree or should I poke Mark about it?

I'd expect to take it through my tree but please allow a reasonable time for reviews...

Sure, thanks. I just wanted to make sure this series didn't fall through the cracks if there was some confusion on who is supposed to pick it up.

Signature · 3 lines
Regards,
Pratyush Yadav
Texas Instruments Inc.
maintainer
#10 lore raw
In reply to Pratyush Yadav
Quoted 8 lines · Pratyush Yadav

This series adds bindings for peripheral-specific SPI controller properties. See patch 1 for more info on the motivations behind this.

This is the best approach that I came up with with my limited knowledge of JSON schema. It has some limitations that are mentioned in patch 1. I don't know of any better ways to model this. Suggestions are welcome!

[...]

Applied to

https://git.kernel.org/pub/scm/linux/kernel/git/broonie/spi.git for-next

Thanks!

[1/3] spi: dt-bindings: add schema listing peripheral-specific properties

      commit: 8762b07c95c18fbbe1c6b3eb1e8e686091c346b5
[2/3] spi: dt-bindings: cdns,qspi-nor: Move peripheral-specific properties out
      commit: b6bdc6e043906c70e949b2747772e6aa1d36f2a3
[3/3] dt-bindings: mtd: spi-nor: Add a reference to spi-peripheral-props.yaml
      commit: e9d7c323cfbbd07c365a419b4ce3dc2f161442c7

All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying to this mail.

Thanks,
Mark

______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/