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 Common Properties
8
9maintainers:
10  - Mark Brown <[email protected]>
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-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      The simplest way to obtain an active-high CS signal is to configure the
73      controller's cs-gpio property with the ACTIVE_HIGH flag and set the
74      peripheral's spi-cs-high property. See example below for a better
75      understanding.
76
77  fifo-depth:
78    $ref: /schemas/types.yaml#/definitions/uint32
79    description:
80      Size of the RX and TX data FIFOs in bytes.
81
82  rx-fifo-depth:
83    $ref: /schemas/types.yaml#/definitions/uint32
84    description:
85      Size of the RX data FIFO in bytes.
86
87  tx-fifo-depth:
88    $ref: /schemas/types.yaml#/definitions/uint32
89    description:
90      Size of the TX data FIFO in bytes.
91
92  num-cs:
93    $ref: /schemas/types.yaml#/definitions/uint32
94    description:
95      Total number of chip selects.
96
97  spi-slave:
98    $ref: /schemas/types.yaml#/definitions/flag
99    description:
100      The SPI controller acts as a slave, instead of a master.
101
102  slave:
103    type: object
104
105    properties:
106      compatible:
107        description:
108          Compatible of the SPI device.
109
110    required:
111      - compatible
112
113patternProperties:
114  "^.*@[0-9a-f]+$":
115    type: object
116    $ref: spi-peripheral-props.yaml
117    additionalProperties: true
118
119    properties:
120      spi-3wire:
121        $ref: /schemas/types.yaml#/definitions/flag
122        description:
123          The device requires 3-wire mode.
124
125      spi-cpha:
126        $ref: /schemas/types.yaml#/definitions/flag
127        description:
128          The device requires shifted clock phase (CPHA) mode.
129
130      spi-cpol:
131        $ref: /schemas/types.yaml#/definitions/flag
132        description:
133          The device requires inverse clock polarity (CPOL) mode.
134
135    required:
136      - compatible
137      - reg
138
139dependencies:
140  rx-fifo-depth: [ tx-fifo-depth ]
141  tx-fifo-depth: [ rx-fifo-depth ]
142
143allOf:
144  - if:
145      not:
146        required:
147          - spi-slave
148    then:
149      properties:
150        "#address-cells":
151          const: 1
152    else:
153      properties:
154        "#address-cells":
155          const: 0
156  - not:
157      required:
158        - fifo-depth
159        - rx-fifo-depth
160  - not:
161      required:
162        - fifo-depth
163        - tx-fifo-depth
164
165additionalProperties: true
166
167examples:
168  - |
169    spi@80010000 {
170        #address-cells = <1>;
171        #size-cells = <0>;
172        compatible = "fsl,imx28-spi";
173        reg = <0x80010000 0x2000>;
174        interrupts = <96>;
175        dmas = <&dma_apbh 0>;
176        dma-names = "rx-tx";
177
178        display@0 {
179            compatible = "lg,lg4573";
180            spi-max-frequency = <1000000>;
181            reg = <0>;
182        };
183
184        sensor@1 {
185            compatible = "bosch,bme680";
186            spi-max-frequency = <100000>;
187            reg = <1>;
188        };
189
190        flash@2 {
191            compatible = "jedec,spi-nor";
192            spi-max-frequency = <50000000>;
193            reg = <2>, <3>;
194            stacked-memories = /bits/ 64 <0x10000000 0x10000000>;
195        };
196    };
197
198  - |
199    #include <dt-bindings/gpio/gpio.h>
200
201    spi@20204000 {
202        #address-cells = <1>;
203        #size-cells = <0>;
204        compatible = "brcm,bcm2835-spi";
205        reg = <0x7e204000 0x1000>;
206        interrupts = <2 22>;
207        clocks = <&clk_spi>;
208        cs-gpios = <&gpio 8 GPIO_ACTIVE_HIGH>;
209
210        display@0 {
211            compatible = "lg,lg4573";
212            spi-max-frequency = <1000000>;
213            reg = <0>;
214            spi-cs-high;
215        };
216    };
217