Documentation/devicetree/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   slave:
  83     type: object
  84
  85     properties:
  86       compatible:
  87         description:
  88           Compatible of the SPI device.
  89
  90     required:
  91       - compatible
  92
  93 patternProperties:
  94   "^.*@[0-9a-f]+$":
  95     type: object
  96
  97     properties:
  98       compatible:
  99         description:
 100           Compatible of the SPI device.
 101
 102       reg:
 103         minItems: 1
 104         maxItems: 256
 105         items:
 106           minimum: 0
 107           maximum: 256
 108         description:
 109           Chip select used by the device.
 110
 111       spi-3wire:
 112         $ref: /schemas/types.yaml#/definitions/flag
 113         description:
 114           The device requires 3-wire mode.
 115
 116       spi-cpha:
 117         $ref: /schemas/types.yaml#/definitions/flag
 118         description:
 119           The device requires shifted clock phase (CPHA) mode.
 120
 121       spi-cpol:
 122         $ref: /schemas/types.yaml#/definitions/flag
 123         description:
 124           The device requires inverse clock polarity (CPOL) mode.
 125
 126       spi-cs-high:
 127         $ref: /schemas/types.yaml#/definitions/flag
 128         description:
 129           The device requires the chip select active high.
 130
 131       spi-lsb-first:
 132         $ref: /schemas/types.yaml#/definitions/flag
 133         description:
 134           The device requires the LSB first mode.
 135
 136       spi-max-frequency:
 137         $ref: /schemas/types.yaml#/definitions/uint32
 138         description:
 139           Maximum SPI clocking speed of the device in Hz.
 140
 141       spi-rx-bus-width:
 142         description:
 143           Bus width to the SPI bus used for read transfers.
 144           If 0 is provided, then no RX will be possible on this device.
 145         $ref: /schemas/types.yaml#/definitions/uint32
 146         enum: [0, 1, 2, 4, 8]
 147         default: 1
 148
 149       spi-rx-delay-us:
 150         description:
 151           Delay, in microseconds, after a read transfer.
 152
 153       spi-tx-bus-width:
 154         description:
 155           Bus width to the SPI bus used for write transfers.
 156           If 0 is provided, then no TX will be possible on this device.
 157         $ref: /schemas/types.yaml#/definitions/uint32
 158         enum: [0, 1, 2, 4, 8]
 159         default: 1
 160
 161       spi-tx-delay-us:
 162         description:
 163           Delay, in microseconds, after a write transfer.
 164
 165     required:
 166       - compatible
 167       - reg
 168
 169 allOf:
 170   - if:
 171       not:
 172         required:
 173           - spi-slave
 174     then:
 175       properties:
 176         "#address-cells":
 177           const: 1
 178     else:
 179       properties:
 180         "#address-cells":
 181           const: 0
 182
 183 additionalProperties: true
 184
 185 examples:
 186   - |
 187     spi@80010000 {
 188         #address-cells = <1>;
 189         #size-cells = <0>;
 190         compatible = "fsl,imx28-spi";
 191         reg = <0x80010000 0x2000>;
 192         interrupts = <96>;
 193         dmas = <&dma_apbh 0>;
 194         dma-names = "rx-tx";
 195
 196         display@0 {
 197             compatible = "lg,lg4573";
 198             spi-max-frequency = <1000000>;
 199             reg = <0>;
 200         };
 201
 202         sensor@1 {
 203             compatible = "bosch,bme680";
 204             spi-max-frequency = <100000>;
 205             reg = <1>;
 206         };
 207     };