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 Common Properties
   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.yaml. 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   wakeup-source:
 297     $ref: /schemas/types.yaml#/definitions/flag
 298     description:
 299       SDIO only. Enables wake up of host system on SDIO IRQ assertion.
 300
 301   vmmc-supply:
 302     description:
 303       Supply for the card power
 304
 305   vqmmc-supply:
 306     description:
 307       Supply for the bus IO line power, such as a level shifter.
 308       If the level shifter is controlled by a GPIO line, this shall
 309       be modeled as a "regulator-fixed" with a GPIO line for
 310       switching the level shifter on/off.
 311
 312   mmc-pwrseq:
 313     $ref: /schemas/types.yaml#/definitions/phandle
 314     description:
 315       System-on-Chip designs may specify a specific MMC power
 316       sequence. To successfully detect an (e)MMC/SD/SDIO card, that
 317       power sequence must be maintained while initializing the card.
 318
 319 patternProperties:
 320   "^.*@[0-9]+$":
 321     type: object
 322     description: |
 323       On embedded systems the cards connected to a host may need
 324       additional properties. These can be specified in subnodes to the
 325       host controller node. The subnodes are identified by the
 326       standard \'reg\' property. Which information exactly can be
 327       specified depends on the bindings for the SDIO function driver
 328       for the subnode, as specified by the compatible string.
 329
 330     properties:
 331       compatible:
 332         description: |
 333           Name of SDIO function following generic names recommended
 334           practice
 335
 336       reg:
 337         items:
 338           - minimum: 0
 339             maximum: 7
 340             description:
 341               Must contain the SDIO function number of the function this
 342               subnode describes. A value of 0 denotes the memory SD
 343               function, values from 1 to 7 denote the SDIO functions.
 344
 345     required:
 346       - reg
 347
 348   "^clk-phase-(legacy|sd-hs|mmc-(hs|hs[24]00|ddr52)|uhs-(sdr(12|25|50|104)|ddr50))$":
 349     $ref: /schemas/types.yaml#/definitions/uint32-array
 350
 351     minItems: 2
 352     maxItems: 2
 353     items:
 354       minimum: 0
 355       maximum: 359
 356       description:
 357         Set the clock (phase) delays which are to be configured in the
 358         controller while switching to particular speed mode. These values
 359         are in pair of degrees.
 360
 361 dependencies:
 362   cd-debounce-delay-ms: [ cd-gpios ]
 363   fixed-emmc-driver-type: [ non-removable ]
 364
 365 additionalProperties: true
 366
 367 examples:
 368   - |
 369     mmc3: mmc@1c12000 {
 370         #address-cells = <1>;
 371         #size-cells = <0>;
 372         reg = <0x1c12000 0x200>;
 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: wifi@1 {
 381             reg = <1>;
 382             compatible = "brcm,bcm4329-fmac";
 383             interrupt-parent = <&pio>;
 384             interrupts = <10 8>;
 385             interrupt-names = "host-wake";
 386         };
 387     };