[mirror_ubuntu-artful-kernel.git] / Documentation / devicetree / bindings / mmc / synopsys-dw-mshc.txt

* Synopsys Designware Mobile Storage Host Controller

The Synopsys designware mobile storage host controller is used to interface
a SoC with storage medium such as eMMC or SD/MMC cards. This file documents
differences between the core mmc properties described by mmc.txt and the
properties used by the Synopsys Designware Mobile Storage Host Controller.

Required Properties:

* compatible: should be
	- snps,dw-mshc: for controllers compliant with synopsys dw-mshc.
* #address-cells: should be 1.
* #size-cells: should be 0.

# Slots: The slot specific information are contained within child-nodes with
  each child-node representing a supported slot. There should be atleast one
  child node representing a card slot. The name of the child node representing
  the slot is recommended to be slot@n where n is the unique number of the slot
  connected to the controller. The following are optional properties which
  can be included in the slot child node.

	* reg: specifies the physical slot number. The valid values of this
	  property is 0 to (num-slots -1), where num-slots is the value
	  specified by the num-slots property.

	* bus-width: as documented in mmc core bindings.

	* wp-gpios: specifies the write protect gpio line. The format of the
	  gpio specifier depends on the gpio controller. If a GPIO is not used
	  for write-protect, this property is optional.

	* disable-wp: If the wp-gpios property isn't present then (by default)
	  we'd assume that the write protect is hooked up directly to the
	  controller's special purpose write protect line (accessible via
	  the WRTPRT register).  However, it's possible that we simply don't
	  want write protect.  In that case specify 'disable-wp'.
	  NOTE: This property is not required for slots known to always
	  connect to eMMC or SDIO cards.

Optional properties:

* resets: phandle + reset specifier pair, intended to represent hardware
  reset signal present internally in some host controller IC designs.
  See Documentation/devicetree/bindings/reset/reset.txt for details.

* reset-names: request name for using "resets" property. Must be "reset".
	(It will be used together with "resets" property.)

* clocks: from common clock binding: handle to biu and ciu clocks for the
  bus interface unit clock and the card interface unit clock.

* clock-names: from common clock binding: Shall be "biu" and "ciu".
  If the biu clock is missing we'll simply skip enabling it.  If the
  ciu clock is missing we'll just assume that the clock is running at
  clock-frequency.  It is an error to omit both the ciu clock and the
  clock-frequency.

* clock-frequency: should be the frequency (in Hz) of the ciu clock.  If this
  is specified and the ciu clock is specified then we'll try to set the ciu
  clock to this at probe time.

* clock-freq-min-max (DEPRECATED): Minimum and Maximum clock frequency for card output
  clock(cclk_out). If it's not specified, max is 200MHZ and min is 400KHz by default.
	  (Use the "max-frequency" instead of "clock-freq-min-max".)

* num-slots: specifies the number of slots supported by the controller.
  The number of physical slots actually used could be equal or less than the
  value specified by num-slots. If this property is not specified, the value
  of num-slot property is assumed to be 1.

* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not
  specified, the default value of the fifo size is determined from the
  controller registers.

* card-detect-delay: Delay in milli-seconds before detecting card after card
  insert event. The default value is 0.

* data-addr: Override fifo address with value provided by DT. The default FIFO reg
  offset is assumed as 0x100 (version < 0x240A) and 0x200(version >= 0x240A) by
  driver. If the controller does not follow this rule, please use this property
  to set fifo address in device tree.

* fifo-watermark-aligned: Data done irq is expected if data length is less than
  watermark in PIO mode. But fifo watermark is requested to be aligned with data
  length in some SoC so that TX/RX irq can be generated with data done irq. Add this
  watermark quirk to mark this requirement and force fifo watermark setting
  accordingly.

* vmmc-supply: The phandle to the regulator to use for vmmc.  If this is
  specified we'll defer probe until we can find this regulator.

* dmas: List of DMA specifiers with the controller specific format as described
  in the generic DMA client binding. Refer to dma.txt for details.

* dma-names: request names for generic DMA client binding. Must be "rx-tx".
  Refer to dma.txt for details.

Aliases:

- All the MSHC controller nodes should be represented in the aliases node using
  the following format 'mshc{n}' where n is a unique number for the alias.

Example:

The MSHC controller node can be split into two portions, SoC specific and
board specific portions as listed below.

	dwmmc0@12200000 {
		compatible = "snps,dw-mshc";
		clocks = <&clock 351>, <&clock 132>;
		clock-names = "biu", "ciu";
		reg = <0x12200000 0x1000>;
		interrupts = <0 75 0>;
		#address-cells = <1>;
		#size-cells = <0>;
		data-addr = <0x200>;
		fifo-watermark-aligned;
		resets = <&rst 20>;
		reset-names = "reset";
	};

[board specific internal DMA resources]

	dwmmc0@12200000 {
		clock-frequency = <400000000>;
		clock-freq-min-max = <400000 200000000>;
		num-slots = <1>;
		broken-cd;
		fifo-depth = <0x80>;
		card-detect-delay = <200>;
		vmmc-supply = <&buck8>;
		bus-width = <8>;
		cap-mmc-highspeed;
		cap-sd-highspeed;
	};

[board specific generic DMA request binding]

	dwmmc0@12200000 {
		clock-frequency = <400000000>;
		clock-freq-min-max = <400000 200000000>;
		num-slots = <1>;
		broken-cd;
		fifo-depth = <0x80>;
		card-detect-delay = <200>;
		vmmc-supply = <&buck8>;
		bus-width = <8>;
		cap-mmc-highspeed;
		cap-sd-highspeed;
		dmas = <&pdma 12>;
		dma-names = "rx-tx";
	};
Commit	Line	Data
53126a2f	1	* Synopsys Designware Mobile Storage Host Controller
c91eab4b	2
53126a2f	3	The Synopsys designware mobile storage host controller is used to interface
c91eab4b TA	4	a SoC with storage medium such as eMMC or SD/MMC cards. This file documents
c91eab4b TA	5	differences between the core mmc properties described by mmc.txt and the
53126a2f	6	properties used by the Synopsys Designware Mobile Storage Host Controller.
c91eab4b TA	7
	8	Required Properties:
	9
	10	* compatible: should be
53126a2f	11	- snps,dw-mshc: for controllers compliant with synopsys dw-mshc.
c91eab4b TA	12	* #address-cells: should be 1.
	13	* #size-cells: should be 0.
	14
	15	# Slots: The slot specific information are contained within child-nodes with
	16	each child-node representing a supported slot. There should be atleast one
	17	child node representing a card slot. The name of the child node representing
	18	the slot is recommended to be slot@n where n is the unique number of the slot
bdf63108	19	connected to the controller. The following are optional properties which
c91eab4b TA	20	can be included in the slot child node.
	21
	22	* reg: specifies the physical slot number. The valid values of this
	23	property is 0 to (num-slots -1), where num-slots is the value
	24	specified by the num-slots property.
	25
	26	* bus-width: as documented in mmc core bindings.
	27
	28	* wp-gpios: specifies the write protect gpio line. The format of the
a70aaa64 DA	29	gpio specifier depends on the gpio controller. If a GPIO is not used
	30	for write-protect, this property is optional.
	31
	32	* disable-wp: If the wp-gpios property isn't present then (by default)
	33	we'd assume that the write protect is hooked up directly to the
	34	controller's special purpose write protect line (accessible via
	35	the WRTPRT register). However, it's possible that we simply don't
	36	want write protect. In that case specify 'disable-wp'.
	37	NOTE: This property is not required for slots known to always
	38	connect to eMMC or SDIO cards.
c91eab4b TA	39
	40	Optional properties:
	41
fdc22b6b GX	42	* resets: phandle + reset specifier pair, intended to represent hardware
	43	reset signal present internally in some host controller IC designs.
	44	See Documentation/devicetree/bindings/reset/reset.txt for details.
	45
9a76a3ac JC	46	* reset-names: request name for using "resets" property. Must be "reset".
	47	(It will be used together with "resets" property.)
	48
3c6d89ea DA	49	* clocks: from common clock binding: handle to biu and ciu clocks for the
	50	bus interface unit clock and the card interface unit clock.
	51
	52	* clock-names: from common clock binding: Shall be "biu" and "ciu".
	53	If the biu clock is missing we'll simply skip enabling it. If the
	54	ciu clock is missing we'll just assume that the clock is running at
	55	clock-frequency. It is an error to omit both the ciu clock and the
	56	clock-frequency.
	57
	58	* clock-frequency: should be the frequency (in Hz) of the ciu clock. If this
	59	is specified and the ciu clock is specified then we'll try to set the ciu
	60	clock to this at probe time.
	61
b023030f	62	* clock-freq-min-max (DEPRECATED): Minimum and Maximum clock frequency for card output
1f44a2a5	63	clock(cclk_out). If it's not specified, max is 200MHZ and min is 400KHz by default.
b023030f	64	(Use the "max-frequency" instead of "clock-freq-min-max".)
1f44a2a5	65
c91eab4b TA	66	* num-slots: specifies the number of slots supported by the controller.
	67	The number of physical slots actually used could be equal or less than the
	68	value specified by num-slots. If this property is not specified, the value
	69	of num-slot property is assumed to be 1.
	70
	71	* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not
	72	specified, the default value of the fifo size is determined from the
	73	controller registers.
	74
	75	* card-detect-delay: Delay in milli-seconds before detecting card after card
	76	insert event. The default value is 0.
	77
4a80f776 JN	78	* data-addr: Override fifo address with value provided by DT. The default FIFO reg
	79	offset is assumed as 0x100 (version < 0x240A) and 0x200(version >= 0x240A) by
	80	driver. If the controller does not follow this rule, please use this property
	81	to set fifo address in device tree.
	82
	83	* fifo-watermark-aligned: Data done irq is expected if data length is less than
	84	watermark in PIO mode. But fifo watermark is requested to be aligned with data
	85	length in some SoC so that TX/RX irq can be generated with data done irq. Add this
	86	watermark quirk to mark this requirement and force fifo watermark setting
	87	accordingly.
	88
870556a3 DA	89	* vmmc-supply: The phandle to the regulator to use for vmmc. If this is
	90	specified we'll defer probe until we can find this regulator.
	91
87ffa7d3 SL	92	* dmas: List of DMA specifiers with the controller specific format as described
	93	in the generic DMA client binding. Refer to dma.txt for details.
	94
	95	* dma-names: request names for generic DMA client binding. Must be "rx-tx".
	96	Refer to dma.txt for details.
	97
c91eab4b TA	98	Aliases:
	99
	100	- All the MSHC controller nodes should be represented in the aliases node using
	101	the following format 'mshc{n}' where n is a unique number for the alias.
	102
	103	Example:
	104
	105	The MSHC controller node can be split into two portions, SoC specific and
	106	board specific portions as listed below.
	107
	108	dwmmc0@12200000 {
	109	compatible = "snps,dw-mshc";
3c6d89ea DA	110	clocks = <&clock 351>, <&clock 132>;
3c6d89ea DA	111	clock-names = "biu", "ciu";
c91eab4b TA	112	reg = <0x12200000 0x1000>;
	113	interrupts = <0 75 0>;
	114	#address-cells = <1>;
	115	#size-cells = <0>;
4a80f776 JN	116	data-addr = <0x200>;
4a80f776 JN	117	fifo-watermark-aligned;
9a76a3ac JC	118	resets = <&rst 20>;
9a76a3ac JC	119	reset-names = "reset";
c91eab4b TA	120	};
c91eab4b TA	121
87ffa7d3 SL	122	[board specific internal DMA resources]
	123
	124	dwmmc0@12200000 {
	125	clock-frequency = <400000000>;
	126	clock-freq-min-max = <400000 200000000>;
	127	num-slots = <1>;
	128	broken-cd;
	129	fifo-depth = <0x80>;
	130	card-detect-delay = <200>;
	131	vmmc-supply = <&buck8>;
	132	bus-width = <8>;
	133	cap-mmc-highspeed;
	134	cap-sd-highspeed;
	135	};
	136
	137	[board specific generic DMA request binding]
	138
c91eab4b	139	dwmmc0@12200000 {
3c6d89ea	140	clock-frequency = <400000000>;
1f44a2a5	141	clock-freq-min-max = <400000 200000000>;
c91eab4b	142	num-slots = <1>;
c91eab4b TA	143	broken-cd;
	144	fifo-depth = <0x80>;
	145	card-detect-delay = <200>;
870556a3	146	vmmc-supply = <&buck8>;
c83c8737 JC	147	bus-width = <8>;
	148	cap-mmc-highspeed;
	149	cap-sd-highspeed;
87ffa7d3 SL	150	dmas = <&pdma 12>;
87ffa7d3 SL	151	dma-names = "rx-tx";
c91eab4b	152	};