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   no-mmc-hs400:
 224     $ref: /schemas/types.yaml#/definitions/flag
 225     description:
 226       All eMMC HS400 modes are not supported.
 227
 228   dsr:
 229     description:
 230       Value the card Driver Stage Register (DSR) should be programmed
 231       with.
 232     $ref: /schemas/types.yaml#/definitions/uint32
 233     minimum: 0
 234     maximum: 0xffff
 235
 236   no-sdio:
 237     $ref: /schemas/types.yaml#/definitions/flag
 238     description:
 239       Controller is limited to send SDIO commands during
 240       initialization.
 241
 242   no-sd:
 243     $ref: /schemas/types.yaml#/definitions/flag
 244     description:
 245       Controller is limited to send SD commands during initialization.
 246
 247   no-mmc:
 248     $ref: /schemas/types.yaml#/definitions/flag
 249     description:
 250       Controller is limited to send MMC commands during
 251       initialization.
 252
 253   fixed-emmc-driver-type:
 254     description:
 255       For non-removable eMMC, enforce this driver type. The value is
 256       the driver type as specified in the eMMC specification (table
 257       206 in spec version 5.1)
 258     $ref: /schemas/types.yaml#/definitions/uint32
 259     minimum: 0
 260     maximum: 4
 261
 262   post-power-on-delay-ms:
 263     description:
 264       It was invented for MMC pwrseq-simple which could be referred to
 265       mmc-pwrseq-simple.txt. But now it\'s reused as a tunable delay
 266       waiting for I/O signalling and card power supply to be stable,
 267       regardless of whether pwrseq-simple is used. Default to 10ms if
 268       no available.
 269     default: 10
 270
 271   supports-cqe:
 272     $ref: /schemas/types.yaml#/definitions/flag
 273     description:
 274       The presence of this property indicates that the corresponding
 275       MMC host controller supports HW command queue feature.
 276
 277   disable-cqe-dcmd:
 278     $ref: /schemas/types.yaml#/definitions/flag
 279     description:
 280       The presence of this property indicates that the MMC
 281       controller\'s command queue engine (CQE) does not support direct
 282       commands (DCMDs).
 283
 284   keep-power-in-suspend:
 285     $ref: /schemas/types.yaml#/definitions/flag
 286     description:
 287       SDIO only. Preserves card power during a suspend/resume cycle.
 288
 289   # Deprecated: enable-sdio-wakeup
 290   wakeup-source:
 291     $ref: /schemas/types.yaml#/definitions/flag
 292     description:
 293       SDIO only. Enables wake up of host system on SDIO IRQ assertion.
 294
 295   vmmc-supply:
 296     description:
 297       Supply for the card power
 298
 299   vqmmc-supply:
 300     description:
 301       Supply for the bus IO line power
 302
 303   mmc-pwrseq:
 304     $ref: /schemas/types.yaml#/definitions/phandle
 305     description:
 306       System-on-Chip designs may specify a specific MMC power
 307       sequence. To successfully detect an (e)MMC/SD/SDIO card, that
 308       power sequence must be maintained while initializing the card.
 309
 310 patternProperties:
 311   "^.*@[0-9]+$":
 312     type: object
 313     description: |
 314       On embedded systems the cards connected to a host may need
 315       additional properties. These can be specified in subnodes to the
 316       host controller node. The subnodes are identified by the
 317       standard \'reg\' property. Which information exactly can be
 318       specified depends on the bindings for the SDIO function driver
 319       for the subnode, as specified by the compatible string.
 320
 321     properties:
 322       compatible:
 323         description: |
 324           Name of SDIO function following generic names recommended
 325           practice
 326
 327       reg:
 328         items:
 329           - minimum: 0
 330             maximum: 7
 331             description:
 332               Must contain the SDIO function number of the function this
 333               subnode describes. A value of 0 denotes the memory SD
 334               function, values from 1 to 7 denote the SDIO functions.
 335
 336       broken-hpi:
 337         $ref: /schemas/types.yaml#/definitions/flag
 338         description:
 339           Use this to indicate that the mmc-card has a broken hpi
 340           implementation, and that hpi should not be used.
 341
 342     required:
 343       - reg
 344
 345   "^clk-phase-(legacy|sd-hs|mmc-(hs|hs[24]00|ddr52)|uhs-(sdr(12|25|50|104)|ddr50))$":
 346     $ref: /schemas/types.yaml#/definitions/uint32-array
 347
 348     minItems: 2
 349     maxItems: 2
 350     items:
 351       minimum: 0
 352       maximum: 359
 353       description:
 354         Set the clock (phase) delays which are to be configured in the
 355         controller while switching to particular speed mode. These values
 356         are in pair of degrees.
 357
 358 dependencies:
 359   cd-debounce-delay-ms: [ cd-gpios ]
 360   fixed-emmc-driver-type: [ non-removable ]
 361
 362 additionalProperties: true
 363
 364 examples:
 365   - |
 366     mmc3: mmc@1c12000 {
 367         #address-cells = <1>;
 368         #size-cells = <0>;
 369         reg = <0x1c12000 0x200>;
 370         pinctrl-names = "default";
 371         pinctrl-0 = <&mmc3_pins_a>;
 372         vmmc-supply = <&reg_vmmc3>;
 373         bus-width = <4>;
 374         non-removable;
 375         mmc-pwrseq = <&sdhci0_pwrseq>;
 376
 377         brcmf: wifi@1 {
 378             reg = <1>;
 379             compatible = "brcm,bcm4329-fmac";
 380             interrupt-parent = <&pio>;
 381             interrupts = <10 8>;
 382             interrupt-names = "host-wake";
 383         };
 384     };