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        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
180additionalProperties: true
181
182examples:
183  - |
184    spi@80010000 {
185        #address-cells = <1>;
186        #size-cells = <0>;
187        compatible = "fsl,imx28-spi";
188        reg = <0x80010000 0x2000>;
189        interrupts = <96>;
190        dmas = <&dma_apbh 0>;
191        dma-names = "rx-tx";
192
193        display@0 {
194            compatible = "lg,lg4573";
195            spi-max-frequency = <1000000>;
196            reg = <0>;
197        };
198
199        sensor@1 {
200            compatible = "bosch,bme680";
201            spi-max-frequency = <100000>;
202            reg = <1>;
203        };
204    };
205