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   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
  21 properties:
  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
 320 patternProperties:
 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
 362 dependencies:
 363   cd-debounce-delay-ms: [ cd-gpios ]
 364   fixed-emmc-driver-type: [ non-removable ]
 365
 366 additionalProperties: true
 367
 368 examples:
 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     };