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
7title: SPI Controller Generic Binding
8
9maintainers:
10  - Mark Brown <broonie@kernel.org>
11
12description: |
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
18properties:
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
82allOf:
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
96patternProperties:
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        minItems: 1
118        maxItems: 256
119        items:
120          minimum: 0
121          maximum: 256
122        description:
123          Chip select used by the device.
124
125      spi-3wire:
126        $ref: /schemas/types.yaml#/definitions/flag
127        description:
128          The device requires 3-wire mode.
129
130      spi-cpha:
131        $ref: /schemas/types.yaml#/definitions/flag
132        description:
133          The device requires shifted clock phase (CPHA) mode.
134
135      spi-cpol:
136        $ref: /schemas/types.yaml#/definitions/flag
137        description:
138          The device requires inverse clock polarity (CPOL) mode.
139
140      spi-cs-high:
141        $ref: /schemas/types.yaml#/definitions/flag
142        description:
143          The device requires the chip select active high.
144
145      spi-lsb-first:
146        $ref: /schemas/types.yaml#/definitions/flag
147        description:
148          The device requires the LSB first mode.
149
150      spi-max-frequency:
151        $ref: /schemas/types.yaml#/definitions/uint32
152        description:
153          Maximum SPI clocking speed of the device in Hz.
154
155      spi-rx-bus-width:
156        description:
157          Bus width to the SPI bus used for read transfers.
158          If 0 is provided, then no RX will be possible on this device.
159        $ref: /schemas/types.yaml#/definitions/uint32
160        enum: [0, 1, 2, 4, 8]
161        default: 1
162
163      spi-rx-delay-us:
164        description:
165          Delay, in microseconds, after a read transfer.
166
167      spi-tx-bus-width:
168        description:
169          Bus width to the SPI bus used for write transfers.
170          If 0 is provided, then no TX will be possible on this device.
171        $ref: /schemas/types.yaml#/definitions/uint32
172        enum: [0, 1, 2, 4, 8]
173        default: 1
174
175      spi-tx-delay-us:
176        description:
177          Delay, in microseconds, after a write transfer.
178
179    required:
180      - compatible
181      - reg
182
183additionalProperties: true
184
185examples:
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    };
208