Documentation/devicetree/bindings/mmc/mmc-controller.yaml

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