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 Common Properties
   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-9]|[1-9][0-9]+))?$"
  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   fifo-depth:
  73     $ref: /schemas/types.yaml#/definitions/uint32
  74     description:
  75       Size of the RX and TX data FIFOs in bytes.
  76
  77   rx-fifo-depth:
  78     $ref: /schemas/types.yaml#/definitions/uint32
  79     description:
  80       Size of the RX data FIFO in bytes.
  81
  82   tx-fifo-depth:
  83     $ref: /schemas/types.yaml#/definitions/uint32
  84     description:
  85       Size of the TX data FIFO in bytes.
  86
  87   num-cs:
  88     $ref: /schemas/types.yaml#/definitions/uint32
  89     description:
  90       Total number of chip selects.
  91
  92   spi-slave:
  93     $ref: /schemas/types.yaml#/definitions/flag
  94     description:
  95       The SPI controller acts as a slave, instead of a master.
  96
  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 patternProperties:
 109   "^.*@[0-9a-f]+$":
 110     type: object
 111     $ref: spi-peripheral-props.yaml
 112     additionalProperties: true
 113
 114     properties:
 115       spi-3wire:
 116         $ref: /schemas/types.yaml#/definitions/flag
 117         description:
 118           The device requires 3-wire mode.
 119
 120       spi-cpha:
 121         $ref: /schemas/types.yaml#/definitions/flag
 122         description:
 123           The device requires shifted clock phase (CPHA) mode.
 124
 125       spi-cpol:
 126         $ref: /schemas/types.yaml#/definitions/flag
 127         description:
 128           The device requires inverse clock polarity (CPOL) mode.
 129
 130     required:
 131       - compatible
 132       - reg
 133
 134 dependencies:
 135   rx-fifo-depth: [ tx-fifo-depth ]
 136   tx-fifo-depth: [ rx-fifo-depth ]
 137
 138 allOf:
 139   - if:
 140       not:
 141         required:
 142           - spi-slave
 143     then:
 144       properties:
 145         "#address-cells":
 146           const: 1
 147     else:
 148       properties:
 149         "#address-cells":
 150           const: 0
 151   - not:
 152       required:
 153         - fifo-depth
 154         - rx-fifo-depth
 155   - not:
 156       required:
 157         - fifo-depth
 158         - tx-fifo-depth
 159
 160 additionalProperties: true
 161
 162 examples:
 163   - |
 164     spi@80010000 {
 165         #address-cells = <1>;
 166         #size-cells = <0>;
 167         compatible = "fsl,imx28-spi";
 168         reg = <0x80010000 0x2000>;
 169         interrupts = <96>;
 170         dmas = <&dma_apbh 0>;
 171         dma-names = "rx-tx";
 172
 173         display@0 {
 174             compatible = "lg,lg4573";
 175             spi-max-frequency = <1000000>;
 176             reg = <0>;
 177         };
 178
 179         sensor@1 {
 180             compatible = "bosch,bme680";
 181             spi-max-frequency = <100000>;
 182             reg = <1>;
 183         };
 184
 185         flash@2 {
 186             compatible = "jedec,spi-nor";
 187             spi-max-frequency = <50000000>;
 188             reg = <2>, <3>;
 189             stacked-memories = /bits/ 64 <0x10000000 0x10000000>;
 190         };
 191     };