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 Common Properties
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.yaml. 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  wakeup-source:
297    $ref: /schemas/types.yaml#/definitions/flag
298    description:
299      SDIO only. Enables wake up of host system on SDIO IRQ assertion.
300
301  vmmc-supply:
302    description:
303      Supply for the card power
304
305  vqmmc-supply:
306    description:
307      Supply for the bus IO line power, such as a level shifter.
308      If the level shifter is controlled by a GPIO line, this shall
309      be modeled as a "regulator-fixed" with a GPIO line for
310      switching the level shifter on/off.
311
312  mmc-pwrseq:
313    $ref: /schemas/types.yaml#/definitions/phandle
314    description:
315      System-on-Chip designs may specify a specific MMC power
316      sequence. To successfully detect an (e)MMC/SD/SDIO card, that
317      power sequence must be maintained while initializing the card.
318
319patternProperties:
320  "^.*@[0-9]+$":
321    type: object
322    description: |
323      On embedded systems the cards connected to a host may need
324      additional properties. These can be specified in subnodes to the
325      host controller node. The subnodes are identified by the
326      standard \'reg\' property. Which information exactly can be
327      specified depends on the bindings for the SDIO function driver
328      for the subnode, as specified by the compatible string.
329
330    properties:
331      compatible:
332        description: |
333          Name of SDIO function following generic names recommended
334          practice
335
336      reg:
337        items:
338          - minimum: 0
339            maximum: 7
340            description:
341              Must contain the SDIO function number of the function this
342              subnode describes. A value of 0 denotes the memory SD
343              function, values from 1 to 7 denote the SDIO functions.
344
345    required:
346      - reg
347
348  "^clk-phase-(legacy|sd-hs|mmc-(hs|hs[24]00|ddr52)|uhs-(sdr(12|25|50|104)|ddr50))$":
349    $ref: /schemas/types.yaml#/definitions/uint32-array
350
351    minItems: 2
352    maxItems: 2
353    items:
354      minimum: 0
355      maximum: 359
356      description:
357        Set the clock (phase) delays which are to be configured in the
358        controller while switching to particular speed mode. These values
359        are in pair of degrees.
360
361dependencies:
362  cd-debounce-delay-ms: [ cd-gpios ]
363  fixed-emmc-driver-type: [ non-removable ]
364
365additionalProperties: true
366
367examples:
368  - |
369    mmc3: mmc@1c12000 {
370        #address-cells = <1>;
371        #size-cells = <0>;
372        reg = <0x1c12000 0x200>;
373        pinctrl-names = "default";
374        pinctrl-0 = <&mmc3_pins_a>;
375        vmmc-supply = <&reg_vmmc3>;
376        bus-width = <4>;
377        non-removable;
378        mmc-pwrseq = <&sdhci0_pwrseq>;
379
380        brcmf: wifi@1 {
381            reg = <1>;
382            compatible = "brcm,bcm4329-fmac";
383            interrupt-parent = <&pio>;
384            interrupts = <10 8>;
385            interrupt-names = "host-wake";
386        };
387    };
388