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 <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    $ref: spi-peripheral-props.yaml
97    additionalProperties: true
98
99    properties:
100      spi-3wire:
101        $ref: /schemas/types.yaml#/definitions/flag
102        description:
103          The device requires 3-wire mode.
104
105      spi-cpha:
106        $ref: /schemas/types.yaml#/definitions/flag
107        description:
108          The device requires shifted clock phase (CPHA) mode.
109
110      spi-cpol:
111        $ref: /schemas/types.yaml#/definitions/flag
112        description:
113          The device requires inverse clock polarity (CPOL) mode.
114
115    required:
116      - compatible
117      - reg
118
119allOf:
120  - if:
121      not:
122        required:
123          - spi-slave
124    then:
125      properties:
126        "#address-cells":
127          const: 1
128    else:
129      properties:
130        "#address-cells":
131          const: 0
132
133additionalProperties: true
134
135examples:
136  - |
137    spi@80010000 {
138        #address-cells = <1>;
139        #size-cells = <0>;
140        compatible = "fsl,imx28-spi";
141        reg = <0x80010000 0x2000>;
142        interrupts = <96>;
143        dmas = <&dma_apbh 0>;
144        dma-names = "rx-tx";
145
146        display@0 {
147            compatible = "lg,lg4573";
148            spi-max-frequency = <1000000>;
149            reg = <0>;
150        };
151
152        sensor@1 {
153            compatible = "bosch,bme680";
154            spi-max-frequency = <100000>;
155            reg = <1>;
156        };
157
158        flash@2 {
159            compatible = "jedec,spi-nor";
160            spi-max-frequency = <50000000>;
161            reg = <2>, <3>;
162            stacked-memories = /bits/ 64 <0x10000000 0x10000000>;
163        };
164    };
165