Unverified Commit 8762b07c authored by Pratyush Yadav's avatar Pratyush Yadav Committed by Mark Brown
Browse files

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.

Signed-off-by: default avatarPratyush Yadav <p.yadav@ti.com>
Reviewed-by: default avatarRob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20211109181911.2251-2-p.yadav@ti.com


Signed-off-by: default avatarMark Brown <broonie@kernel.org>
parent 8393961c

Documentation/devicetree/bindings/spi/spi-controller.yaml

+2 −67
Original line number Diff line number Diff line
@@ -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

0 → 100644
+87 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/spi/spi-peripheral-props.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#



title: Peripheral-specific properties for a SPI bus.



description:

  Many SPI controllers need to add properties to peripheral devices. They could

  be common properties like spi-max-frequency, spi-cpha, etc. or they could be

  controller specific like delay in clock or data lines, etc. These properties

  need to be defined in the peripheral node because they are per-peripheral and

  there can be multiple peripherals attached to a controller. All those

  properties are listed here. The controller specific properties should go in

  their own separate schema that should be referenced from here.



maintainers:

  - Pratyush Yadav <p.yadav@ti.com>



properties:

  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.



# The controller specific properties go here.



additionalProperties: true