Bindings/spi/spi-controller.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/spi/spi-controller.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: SPI Controller Generic Binding
   8
   9 maintainers:
  10   - Mark Brown <broonie@kernel.org>
  11
  12 description: |
  13   SPI busses can be described with a node for the SPI controller device
  14   and a set of child nodes for each SPI slave on the bus. The system SPI
  15   controller may be described for use in SPI master mode or in SPI slave mode,
  16   but not for both at the same time.
  17
  18 properties:
  19   $nodename:
  20     pattern: "^spi(@.*|-[0-9a-f])*$"
  21
  22   "#address-cells":
  23     enum: [0, 1]
  24
  25   "#size-cells":
  26     const: 0
  27
  28   cs-gpios:
  29     description: |
  30       GPIOs used as chip selects.
  31       If that property is used, the number of chip selects will be
  32       increased automatically with max(cs-gpios, hardware chip selects).
  33
  34       So if, for example, the controller has 4 CS lines, and the
  35       cs-gpios looks like this
  36         cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>;
  37
  38       Then it should be configured so that num_chipselect = 4, with
  39       the following mapping
  40         cs0 : &gpio1 0 0
  41         cs1 : native
  42         cs2 : &gpio1 1 0
  43         cs3 : &gpio1 2 0
  44
  45       The second flag of a gpio descriptor can be GPIO_ACTIVE_HIGH (0)
  46       or GPIO_ACTIVE_LOW(1). Legacy device trees often use 0.
  47
  48       There is a special rule set for combining the second flag of an
  49       cs-gpio with the optional spi-cs-high flag for SPI slaves.
  50
  51       Each table entry defines how the CS pin is to be physically
  52       driven (not considering potential gpio inversions by pinmux):
  53
  54       device node     | cs-gpio       | CS pin state active | Note
  55       ================+===============+=====================+=====
  56       spi-cs-high     | -             | H                   |
  57       -               | -             | L                   |
  58       spi-cs-high     | ACTIVE_HIGH   | H                   |
  59       -               | ACTIVE_HIGH   | L                   | 1
  60       spi-cs-high     | ACTIVE_LOW    | H                   | 2
  61       -               | ACTIVE_LOW    | L                   |
  62
  63       Notes:
  64       1) Should print a warning about polarity inversion.
  65          Here it would be wise to avoid and define the gpio as
  66          ACTIVE_LOW.
  67       2) Should print a warning about polarity inversion
  68          because ACTIVE_LOW is overridden by spi-cs-high.
  69          Should be generally avoided and be replaced by
  70          spi-cs-high + ACTIVE_HIGH.
  71
  72   num-cs:
  73     $ref: /schemas/types.yaml#/definitions/uint32
  74     description:
  75       Total number of chip selects.
  76
  77   spi-slave:
  78     $ref: /schemas/types.yaml#/definitions/flag
  79     description:
  80       The SPI controller acts as a slave, instead of a master.
  81
  82 allOf:
  83   - if:
  84       not:
  85         required:
  86           - spi-slave
  87     then:
  88       properties:
  89         "#address-cells":
  90           const: 1
  91     else:
  92       properties:
  93         "#address-cells":
  94           const: 0
  95
  96 patternProperties:
  97   "^slave$":
  98     type: object
  99
 100     properties:
 101       compatible:
 102         description:
 103           Compatible of the SPI device.
 104
 105     required:
 106       - compatible
 107
 108   "^.*@[0-9a-f]+$":
 109     type: object
 110
 111     properties:
 112       compatible:
 113         description:
 114           Compatible of the SPI device.
 115
 116       reg:
 117         minimum: 0
 118         maximum: 256
 119         description:
 120           Chip select used by the device.
 121
 122       spi-3wire:
 123         $ref: /schemas/types.yaml#/definitions/flag
 124         description:
 125           The device requires 3-wire mode.
 126
 127       spi-cpha:
 128         $ref: /schemas/types.yaml#/definitions/flag
 129         description:
 130           The device requires shifted clock phase (CPHA) mode.
 131
 132       spi-cpol:
 133         $ref: /schemas/types.yaml#/definitions/flag
 134         description:
 135           The device requires inverse clock polarity (CPOL) mode.
 136
 137       spi-cs-high:
 138         $ref: /schemas/types.yaml#/definitions/flag
 139         description:
 140           The device requires the chip select active high.
 141
 142       spi-lsb-first:
 143         $ref: /schemas/types.yaml#/definitions/flag
 144         description:
 145           The device requires the LSB first mode.
 146
 147       spi-max-frequency:
 148         $ref: /schemas/types.yaml#/definitions/uint32
 149         description:
 150           Maximum SPI clocking speed of the device in Hz.
 151
 152       spi-rx-bus-width:
 153         description:
 154           Bus width to the SPI bus used for read transfers.
 155           If 0 is provided, then no RX will be possible on this device.
 156         $ref: /schemas/types.yaml#/definitions/uint32
 157         enum: [0, 1, 2, 4, 8]
 158         default: 1
 159
 160       spi-rx-delay-us:
 161         description:
 162           Delay, in microseconds, after a read transfer.
 163
 164       spi-tx-bus-width:
 165         description:
 166           Bus width to the SPI bus used for write transfers.
 167           If 0 is provided, then no TX will be possible on this device.
 168         $ref: /schemas/types.yaml#/definitions/uint32
 169         enum: [0, 1, 2, 4, 8]
 170         default: 1
 171
 172       spi-tx-delay-us:
 173         description:
 174           Delay, in microseconds, after a write transfer.
 175
 176     required:
 177       - compatible
 178       - reg
 179
 180 additionalProperties: true
 181
 182 examples:
 183   - |
 184     spi@f00 {
 185         #address-cells = <1>;
 186         #size-cells = <0>;
 187         compatible = "fsl,mpc5200b-spi","fsl,mpc5200-spi";
 188         reg = <0xf00 0x20>;
 189         interrupts = <2 13 0 2 14 0>;
 190         interrupt-parent = <&mpc5200_pic>;
 191
 192         ethernet-switch@0 {
 193             compatible = "micrel,ks8995m";
 194             spi-max-frequency = <1000000>;
 195             reg = <0>;
 196         };
 197
 198         codec@1 {
 199             compatible = "ti,tlv320aic26";
 200             spi-max-frequency = <100000>;
 201             reg = <1>;
 202         };
 203     };