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