1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/mmc/mmc-controller.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: MMC Controller Generic Binding
8
9maintainers:
10  - Ulf Hansson <ulf.hansson@linaro.org>
11
12description: |
13  These properties are common to multiple MMC host controllers. Any host
14  that requires the respective functionality should implement them using
15  these definitions.
16
17  It is possible to assign a fixed index mmcN to an MMC host controller
18  (and the corresponding mmcblkN devices) by defining an alias in the
19  /aliases device tree node.
20
21properties:
22  $nodename:
23    pattern: "^mmc(@.*)?$"
24
25  "#address-cells":
26    const: 1
27    description: |
28      The cell is the slot ID if a function subnode is used.
29
30  "#size-cells":
31    const: 0
32
33  # Card Detection.
34  # If none of these properties are supplied, the host native card
35  # detect will be used. Only one of them should be provided.
36
37  broken-cd:
38    $ref: /schemas/types.yaml#/definitions/flag
39    description:
40      There is no card detection available; polling must be used.
41
42  cd-gpios:
43    maxItems: 1
44    description:
45      The card detection will be done using the GPIO provided.
46
47  non-removable:
48    $ref: /schemas/types.yaml#/definitions/flag
49    description:
50      Non-removable slot (like eMMC); assume always present.
51
52  # *NOTE* on CD and WP polarity. To use common for all SD/MMC host
53  # controllers line polarity properties, we have to fix the meaning
54  # of the "normal" and "inverted" line levels. We choose to follow
55  # the SDHCI standard, which specifies both those lines as "active
56  # low." Therefore, using the "cd-inverted" property means, that the
57  # CD line is active high, i.e. it is high, when a card is
58  # inserted. Similar logic applies to the "wp-inverted" property.
59  #
60  # CD and WP lines can be implemented on the hardware in one of two
61  # ways: as GPIOs, specified in cd-gpios and wp-gpios properties, or
62  # as dedicated pins. Polarity of dedicated pins can be specified,
63  # using *-inverted properties. GPIO polarity can also be specified
64  # using the GPIO_ACTIVE_LOW flag. This creates an ambiguity in the
65  # latter case. We choose to use the XOR logic for GPIO CD and WP
66  # lines.  This means, the two properties are "superimposed," for
67  # example leaving the GPIO_ACTIVE_LOW flag clear and specifying the
68  # respective *-inverted property property results in a
69  # double-inversion and actually means the "normal" line polarity is
70  # in effect.
71  wp-inverted:
72    $ref: /schemas/types.yaml#/definitions/flag
73    description:
74      The Write Protect line polarity is inverted.
75
76  cd-inverted:
77    $ref: /schemas/types.yaml#/definitions/flag
78    description:
79      The CD line polarity is inverted.
80
81  # Other properties
82
83  bus-width:
84    description:
85      Number of data lines.
86    $ref: /schemas/types.yaml#/definitions/uint32
87    enum: [1, 4, 8]
88    default: 1
89
90  max-frequency:
91    description: |
92      Maximum operating frequency of the bus:
93        - for eMMC, the maximum supported frequency is 200MHz,
94        - for SD/SDIO cards the SDR104 mode has a max supported
95          frequency of 208MHz,
96        - some mmc host controllers do support a max frequency upto
97          384MHz.
98      So, lets keep the maximum supported value here.
99
100    $ref: /schemas/types.yaml#/definitions/uint32
101    minimum: 400000
102    maximum: 384000000
103
104  disable-wp:
105    $ref: /schemas/types.yaml#/definitions/flag
106    description:
107      When set, no physical write-protect line is present. This
108      property should only be specified when the controller has a
109      dedicated write-protect detection logic. If a GPIO is always used
110      for the write-protect detection logic, it is sufficient to not
111      specify the wp-gpios property in the absence of a write-protect
112      line. Not used in combination with eMMC or SDIO.
113
114  wp-gpios:
115    maxItems: 1
116    description:
117      GPIO to use for the write-protect detection.
118
119  cd-debounce-delay-ms:
120    description:
121      Set delay time before detecting card after card insert
122      interrupt.
123
124  no-1-8-v:
125    $ref: /schemas/types.yaml#/definitions/flag
126    description:
127      When specified, denotes that 1.8V card voltage is not supported
128      on this system, even if the controller claims it.
129
130  cap-sd-highspeed:
131    $ref: /schemas/types.yaml#/definitions/flag
132    description:
133      SD high-speed timing is supported.
134
135  cap-mmc-highspeed:
136    $ref: /schemas/types.yaml#/definitions/flag
137    description:
138      MMC high-speed timing is supported.
139
140  sd-uhs-sdr12:
141    $ref: /schemas/types.yaml#/definitions/flag
142    description:
143      SD UHS SDR12 speed is supported.
144
145  sd-uhs-sdr25:
146    $ref: /schemas/types.yaml#/definitions/flag
147    description:
148      SD UHS SDR25 speed is supported.
149
150  sd-uhs-sdr50:
151    $ref: /schemas/types.yaml#/definitions/flag
152    description:
153      SD UHS SDR50 speed is supported.
154
155  sd-uhs-sdr104:
156    $ref: /schemas/types.yaml#/definitions/flag
157    description:
158      SD UHS SDR104 speed is supported.
159
160  sd-uhs-ddr50:
161    $ref: /schemas/types.yaml#/definitions/flag
162    description:
163      SD UHS DDR50 speed is supported.
164
165  cap-power-off-card:
166    $ref: /schemas/types.yaml#/definitions/flag
167    description:
168      Powering off the card is safe.
169
170  cap-mmc-hw-reset:
171    $ref: /schemas/types.yaml#/definitions/flag
172    description:
173      eMMC hardware reset is supported
174
175  cap-sdio-irq:
176    $ref: /schemas/types.yaml#/definitions/flag
177    description:
178      enable SDIO IRQ signalling on this interface
179
180  full-pwr-cycle:
181    $ref: /schemas/types.yaml#/definitions/flag
182    description:
183      Full power cycle of the card is supported.
184
185  full-pwr-cycle-in-suspend:
186    $ref: /schemas/types.yaml#/definitions/flag
187    description:
188      Full power cycle of the card in suspend is supported.
189
190  mmc-ddr-1_2v:
191    $ref: /schemas/types.yaml#/definitions/flag
192    description:
193      eMMC high-speed DDR mode (1.2V I/O) is supported.
194
195  mmc-ddr-1_8v:
196    $ref: /schemas/types.yaml#/definitions/flag
197    description:
198      eMMC high-speed DDR mode (1.8V I/O) is supported.
199
200  mmc-ddr-3_3v:
201    $ref: /schemas/types.yaml#/definitions/flag
202    description:
203      eMMC high-speed DDR mode (3.3V I/O) is supported.
204
205  mmc-hs200-1_2v:
206    $ref: /schemas/types.yaml#/definitions/flag
207    description:
208      eMMC HS200 mode (1.2V I/O) is supported.
209
210  mmc-hs200-1_8v:
211    $ref: /schemas/types.yaml#/definitions/flag
212    description:
213      eMMC HS200 mode (1.8V I/O) is supported.
214
215  mmc-hs400-1_2v:
216    $ref: /schemas/types.yaml#/definitions/flag
217    description:
218      eMMC HS400 mode (1.2V I/O) is supported.
219
220  mmc-hs400-1_8v:
221    $ref: /schemas/types.yaml#/definitions/flag
222    description:
223      eMMC HS400 mode (1.8V I/O) is supported.
224
225  mmc-hs400-enhanced-strobe:
226    $ref: /schemas/types.yaml#/definitions/flag
227    description:
228      eMMC HS400 enhanced strobe mode is supported
229
230  no-mmc-hs400:
231    $ref: /schemas/types.yaml#/definitions/flag
232    description:
233      All eMMC HS400 modes are not supported.
234
235  dsr:
236    description:
237      Value the card Driver Stage Register (DSR) should be programmed
238      with.
239    $ref: /schemas/types.yaml#/definitions/uint32
240    minimum: 0
241    maximum: 0xffff
242
243  no-sdio:
244    $ref: /schemas/types.yaml#/definitions/flag
245    description:
246      Controller is limited to send SDIO commands during
247      initialization.
248
249  no-sd:
250    $ref: /schemas/types.yaml#/definitions/flag
251    description:
252      Controller is limited to send SD commands during initialization.
253
254  no-mmc:
255    $ref: /schemas/types.yaml#/definitions/flag
256    description:
257      Controller is limited to send MMC commands during
258      initialization.
259
260  fixed-emmc-driver-type:
261    description:
262      For non-removable eMMC, enforce this driver type. The value is
263      the driver type as specified in the eMMC specification (table
264      206 in spec version 5.1)
265    $ref: /schemas/types.yaml#/definitions/uint32
266    minimum: 0
267    maximum: 4
268
269  post-power-on-delay-ms:
270    description:
271      It was invented for MMC pwrseq-simple which could be referred to
272      mmc-pwrseq-simple.txt. But now it\'s reused as a tunable delay
273      waiting for I/O signalling and card power supply to be stable,
274      regardless of whether pwrseq-simple is used. Default to 10ms if
275      no available.
276    default: 10
277
278  supports-cqe:
279    $ref: /schemas/types.yaml#/definitions/flag
280    description:
281      The presence of this property indicates that the corresponding
282      MMC host controller supports HW command queue feature.
283
284  disable-cqe-dcmd:
285    $ref: /schemas/types.yaml#/definitions/flag
286    description:
287      The presence of this property indicates that the MMC
288      controller\'s command queue engine (CQE) does not support direct
289      commands (DCMDs).
290
291  keep-power-in-suspend:
292    $ref: /schemas/types.yaml#/definitions/flag
293    description:
294      SDIO only. Preserves card power during a suspend/resume cycle.
295
296  # Deprecated: enable-sdio-wakeup
297  wakeup-source:
298    $ref: /schemas/types.yaml#/definitions/flag
299    description:
300      SDIO only. Enables wake up of host system on SDIO IRQ assertion.
301
302  vmmc-supply:
303    description:
304      Supply for the card power
305
306  vqmmc-supply:
307    description:
308      Supply for the bus IO line power, such as a level shifter.
309      If the level shifter is controlled by a GPIO line, this shall
310      be modeled as a "regulator-fixed" with a GPIO line for
311      switching the level shifter on/off.
312
313  mmc-pwrseq:
314    $ref: /schemas/types.yaml#/definitions/phandle
315    description:
316      System-on-Chip designs may specify a specific MMC power
317      sequence. To successfully detect an (e)MMC/SD/SDIO card, that
318      power sequence must be maintained while initializing the card.
319
320patternProperties:
321  "^.*@[0-9]+$":
322    type: object
323    description: |
324      On embedded systems the cards connected to a host may need
325      additional properties. These can be specified in subnodes to the
326      host controller node. The subnodes are identified by the
327      standard \'reg\' property. Which information exactly can be
328      specified depends on the bindings for the SDIO function driver
329      for the subnode, as specified by the compatible string.
330
331    properties:
332      compatible:
333        description: |
334          Name of SDIO function following generic names recommended
335          practice
336
337      reg:
338        items:
339          - minimum: 0
340            maximum: 7
341            description:
342              Must contain the SDIO function number of the function this
343              subnode describes. A value of 0 denotes the memory SD
344              function, values from 1 to 7 denote the SDIO functions.
345
346    required:
347      - reg
348
349  "^clk-phase-(legacy|sd-hs|mmc-(hs|hs[24]00|ddr52)|uhs-(sdr(12|25|50|104)|ddr50))$":
350    $ref: /schemas/types.yaml#/definitions/uint32-array
351
352    minItems: 2
353    maxItems: 2
354    items:
355      minimum: 0
356      maximum: 359
357      description:
358        Set the clock (phase) delays which are to be configured in the
359        controller while switching to particular speed mode. These values
360        are in pair of degrees.
361
362dependencies:
363  cd-debounce-delay-ms: [ cd-gpios ]
364  fixed-emmc-driver-type: [ non-removable ]
365
366additionalProperties: true
367
368examples:
369  - |
370    mmc3: mmc@1c12000 {
371        #address-cells = <1>;
372        #size-cells = <0>;
373        reg = <0x1c12000 0x200>;
374        pinctrl-names = "default";
375        pinctrl-0 = <&mmc3_pins_a>;
376        vmmc-supply = <&reg_vmmc3>;
377        bus-width = <4>;
378        non-removable;
379        mmc-pwrseq = <&sdhci0_pwrseq>;
380
381        brcmf: wifi@1 {
382            reg = <1>;
383            compatible = "brcm,bcm4329-fmac";
384            interrupt-parent = <&pio>;
385            interrupts = <10 8>;
386            interrupt-names = "host-wake";
387        };
388    };
389