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
82  slave:
83    type: object
84
85    properties:
86      compatible:
87        description:
88          Compatible of the SPI device.
89
90    required:
91      - compatible
92
93patternProperties:
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
169allOf:
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
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