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     $ref: /schemas/types.yaml#/definitions/uint32
  94     minimum: 400000
  95     maximum: 200000000
  96
  97   disable-wp:
  98     $ref: /schemas/types.yaml#/definitions/flag
  99     description:
 100       When set, no physical write-protect line is present. This
 101       property should only be specified when the controller has a
 102       dedicated write-protect detection logic. If a GPIO is always used
 103       for the write-protect detection logic, it is sufficient to not
 104       specify the wp-gpios property in the absence of a write-protect
 105       line. Not used in combination with eMMC or SDIO.
 106
 107   wp-gpios:
 108     maxItems: 1
 109     description:
 110       GPIO to use for the write-protect detection.
 111
 112   cd-debounce-delay-ms:
 113     description:
 114       Set delay time before detecting card after card insert
 115       interrupt.
 116
 117   no-1-8-v:
 118     $ref: /schemas/types.yaml#/definitions/flag
 119     description:
 120       When specified, denotes that 1.8V card voltage is not supported
 121       on this system, even if the controller claims it.
 122
 123   cap-sd-highspeed:
 124     $ref: /schemas/types.yaml#/definitions/flag
 125     description:
 126       SD high-speed timing is supported.
 127
 128   cap-mmc-highspeed:
 129     $ref: /schemas/types.yaml#/definitions/flag
 130     description:
 131       MMC high-speed timing is supported.
 132
 133   sd-uhs-sdr12:
 134     $ref: /schemas/types.yaml#/definitions/flag
 135     description:
 136       SD UHS SDR12 speed is supported.
 137
 138   sd-uhs-sdr25:
 139     $ref: /schemas/types.yaml#/definitions/flag
 140     description:
 141       SD UHS SDR25 speed is supported.
 142
 143   sd-uhs-sdr50:
 144     $ref: /schemas/types.yaml#/definitions/flag
 145     description:
 146       SD UHS SDR50 speed is supported.
 147
 148   sd-uhs-sdr104:
 149     $ref: /schemas/types.yaml#/definitions/flag
 150     description:
 151       SD UHS SDR104 speed is supported.
 152
 153   sd-uhs-ddr50:
 154     $ref: /schemas/types.yaml#/definitions/flag
 155     description:
 156       SD UHS DDR50 speed is supported.
 157
 158   cap-power-off-card:
 159     $ref: /schemas/types.yaml#/definitions/flag
 160     description:
 161       Powering off the card is safe.
 162
 163   cap-mmc-hw-reset:
 164     $ref: /schemas/types.yaml#/definitions/flag
 165     description:
 166       eMMC hardware reset is supported
 167
 168   cap-sdio-irq:
 169     $ref: /schemas/types.yaml#/definitions/flag
 170     description:
 171       enable SDIO IRQ signalling on this interface
 172
 173   full-pwr-cycle:
 174     $ref: /schemas/types.yaml#/definitions/flag
 175     description:
 176       Full power cycle of the card is supported.
 177
 178   full-pwr-cycle-in-suspend:
 179     $ref: /schemas/types.yaml#/definitions/flag
 180     description:
 181       Full power cycle of the card in suspend is supported.
 182
 183   mmc-ddr-1_2v:
 184     $ref: /schemas/types.yaml#/definitions/flag
 185     description:
 186       eMMC high-speed DDR mode (1.2V I/O) is supported.
 187
 188   mmc-ddr-1_8v:
 189     $ref: /schemas/types.yaml#/definitions/flag
 190     description:
 191       eMMC high-speed DDR mode (1.8V I/O) is supported.
 192
 193   mmc-ddr-3_3v:
 194     $ref: /schemas/types.yaml#/definitions/flag
 195     description:
 196       eMMC high-speed DDR mode (3.3V I/O) is supported.
 197
 198   mmc-hs200-1_2v:
 199     $ref: /schemas/types.yaml#/definitions/flag
 200     description:
 201       eMMC HS200 mode (1.2V I/O) is supported.
 202
 203   mmc-hs200-1_8v:
 204     $ref: /schemas/types.yaml#/definitions/flag
 205     description:
 206       eMMC HS200 mode (1.8V I/O) is supported.
 207
 208   mmc-hs400-1_2v:
 209     $ref: /schemas/types.yaml#/definitions/flag
 210     description:
 211       eMMC HS400 mode (1.2V I/O) is supported.
 212
 213   mmc-hs400-1_8v:
 214     $ref: /schemas/types.yaml#/definitions/flag
 215     description:
 216       eMMC HS400 mode (1.8V I/O) is supported.
 217
 218   mmc-hs400-enhanced-strobe:
 219     $ref: /schemas/types.yaml#/definitions/flag
 220     description:
 221       eMMC HS400 enhanced strobe mode is supported
 222
 223   dsr:
 224     description:
 225       Value the card Driver Stage Register (DSR) should be programmed
 226       with.
 227     $ref: /schemas/types.yaml#/definitions/uint32
 228     minimum: 0
 229     maximum: 0xffff
 230
 231   no-sdio:
 232     $ref: /schemas/types.yaml#/definitions/flag
 233     description:
 234       Controller is limited to send SDIO commands during
 235       initialization.
 236
 237   no-sd:
 238     $ref: /schemas/types.yaml#/definitions/flag
 239     description:
 240       Controller is limited to send SD commands during initialization.
 241
 242   no-mmc:
 243     $ref: /schemas/types.yaml#/definitions/flag
 244     description:
 245       Controller is limited to send MMC commands during
 246       initialization.
 247
 248   fixed-emmc-driver-type:
 249     description:
 250       For non-removable eMMC, enforce this driver type. The value is
 251       the driver type as specified in the eMMC specification (table
 252       206 in spec version 5.1)
 253     $ref: /schemas/types.yaml#/definitions/uint32
 254     minimum: 0
 255     maximum: 4
 256
 257   post-power-on-delay-ms:
 258     description:
 259       It was invented for MMC pwrseq-simple which could be referred to
 260       mmc-pwrseq-simple.txt. But now it\'s reused as a tunable delay
 261       waiting for I/O signalling and card power supply to be stable,
 262       regardless of whether pwrseq-simple is used. Default to 10ms if
 263       no available.
 264     default: 10
 265
 266   supports-cqe:
 267     $ref: /schemas/types.yaml#/definitions/flag
 268     description:
 269       The presence of this property indicates that the corresponding
 270       MMC host controller supports HW command queue feature.
 271
 272   disable-cqe-dcmd:
 273     $ref: /schemas/types.yaml#/definitions/flag
 274     description:
 275       The presence of this property indicates that the MMC
 276       controller\'s command queue engine (CQE) does not support direct
 277       commands (DCMDs).
 278
 279   keep-power-in-suspend:
 280     $ref: /schemas/types.yaml#/definitions/flag
 281     description:
 282       SDIO only. Preserves card power during a suspend/resume cycle.
 283
 284   # Deprecated: enable-sdio-wakeup
 285   wakeup-source:
 286     $ref: /schemas/types.yaml#/definitions/flag
 287     description:
 288       SDIO only. Enables wake up of host system on SDIO IRQ assertion.
 289
 290   vmmc-supply:
 291     description:
 292       Supply for the card power
 293
 294   vqmmc-supply:
 295     description:
 296       Supply for the bus IO line power
 297
 298   mmc-pwrseq:
 299     $ref: /schemas/types.yaml#/definitions/phandle
 300     description:
 301       System-on-Chip designs may specify a specific MMC power
 302       sequence. To successfully detect an (e)MMC/SD/SDIO card, that
 303       power sequence must be maintained while initializing the card.
 304
 305 patternProperties:
 306   "^.*@[0-9]+$":
 307     type: object
 308     description: |
 309       On embedded systems the cards connected to a host may need
 310       additional properties. These can be specified in subnodes to the
 311       host controller node. The subnodes are identified by the
 312       standard \'reg\' property. Which information exactly can be
 313       specified depends on the bindings for the SDIO function driver
 314       for the subnode, as specified by the compatible string.
 315
 316     properties:
 317       compatible:
 318         description: |
 319           Name of SDIO function following generic names recommended
 320           practice
 321
 322       reg:
 323         items:
 324           - minimum: 0
 325             maximum: 7
 326             description:
 327               Must contain the SDIO function number of the function this
 328               subnode describes. A value of 0 denotes the memory SD
 329               function, values from 1 to 7 denote the SDIO functions.
 330
 331       broken-hpi:
 332         $ref: /schemas/types.yaml#/definitions/flag
 333         description:
 334           Use this to indicate that the mmc-card has a broken hpi
 335           implementation, and that hpi should not be used.
 336
 337     required:
 338       - reg
 339
 340   "^clk-phase-(legacy|sd-hs|mmc-(hs|hs[24]00|ddr52)|uhs-(sdr(12|25|50|104)|ddr50))$":
 341     $ref: /schemas/types.yaml#/definitions/uint32-array
 342
 343     minItems: 2
 344     maxItems: 2
 345     items:
 346       minimum: 0
 347       maximum: 359
 348       description:
 349         Set the clock (phase) delays which are to be configured in the
 350         controller while switching to particular speed mode. These values
 351         are in pair of degrees.
 352
 353 dependencies:
 354   cd-debounce-delay-ms: [ cd-gpios ]
 355   fixed-emmc-driver-type: [ non-removable ]
 356
 357 additionalProperties: true
 358
 359 examples:
 360   - |
 361     mmc@ab000000 {
 362         compatible = "sdhci";
 363         reg = <0xab000000 0x200>;
 364         interrupts = <23>;
 365         bus-width = <4>;
 366         cd-gpios = <&gpio 69 0>;
 367         cd-inverted;
 368         wp-gpios = <&gpio 70 0>;
 369         max-frequency = <50000000>;
 370         keep-power-in-suspend;
 371         wakeup-source;
 372         mmc-pwrseq = <&sdhci0_pwrseq>;
 373         clk-phase-sd-hs = <63>, <72>;
 374     };
 375
 376   - |
 377     mmc3: mmc@1c12000 {
 378         #address-cells = <1>;
 379         #size-cells = <0>;
 380         reg = <0x1c12000 0x200>;
 381         pinctrl-names = "default";
 382         pinctrl-0 = <&mmc3_pins_a>;
 383         vmmc-supply = <&reg_vmmc3>;
 384         bus-width = <4>;
 385         non-removable;
 386         mmc-pwrseq = <&sdhci0_pwrseq>;
 387
 388         brcmf: bcrmf@1 {
 389             reg = <1>;
 390             compatible = "brcm,bcm43xx-fmac";
 391             interrupt-parent = <&pio>;
 392             interrupts = <10 8>;
 393             interrupt-names = "host-wake";
 394         };
 395     };