[deliverable/linux.git] / Documentation / devicetree / bindings / mtd / gpmc-nand.txt

Device tree bindings for GPMC connected NANDs

GPMC connected NAND (found on OMAP boards) are represented as child nodes of
the GPMC controller with a name of "nand".

All timing relevant properties as well as generic gpmc child properties are
explained in a separate documents - please refer to
Documentation/devicetree/bindings/bus/ti-gpmc.txt

For NAND specific properties such as ECC modes or bus width, please refer to
Documentation/devicetree/bindings/mtd/nand.txt


Required properties:

 - reg:		The CS line the peripheral is connected to

Optional properties:

 - nand-bus-width: 		Set this numeric value to 16 if the hardware
				is wired that way. If not specified, a bus
				width of 8 is assumed.

 - ti,nand-ecc-opt:		A string setting the ECC layout to use. One of:
		"sw"		1-bit Hamming ecc code via software
		"hw"		<deprecated> use "ham1" instead
		"hw-romcode"	<deprecated> use "ham1" instead
		"ham1"		1-bit Hamming ecc code
		"bch4"		4-bit BCH ecc code
		"bch8"		8-bit BCH ecc code
		"bch16"		16-bit BCH ECC code
		Refer below "How to select correct ECC scheme for your device ?"

 - ti,nand-xfer-type:		A string setting the data transfer type. One of:

		"prefetch-polled"	Prefetch polled mode (default)
		"polled"		Polled mode, without prefetch
		"prefetch-dma"		Prefetch enabled sDMA mode
		"prefetch-irq"		Prefetch enabled irq mode

 - elm_id:	<deprecated> use "ti,elm-id" instead
 - ti,elm-id:	Specifies phandle of the ELM devicetree node.
		ELM is an on-chip hardware engine on TI SoC which is used for
		locating ECC errors for BCHx algorithms. SoC devices which have
		ELM hardware engines should specify this device node in .dtsi
		Using ELM for ECC error correction frees some CPU cycles.

For inline partition table parsing (optional):

 - #address-cells: should be set to 1
 - #size-cells: should be set to 1

Example for an AM33xx board:

	gpmc: gpmc@50000000 {
		compatible = "ti,am3352-gpmc";
		ti,hwmods = "gpmc";
		reg = <0x50000000 0x1000000>;
		interrupts = <100>;
		gpmc,num-cs = <8>;
		gpmc,num-waitpins = <2>;
		#address-cells = <2>;
		#size-cells = <1>;
		ranges = <0 0 0x08000000 0x2000>;	/* CS0: NAND */
		elm_id = <&elm>;

		nand@0,0 {
			reg = <0 0 0>; /* CS0, offset 0 */
			nand-bus-width = <16>;
			ti,nand-ecc-opt = "bch8";
			ti,nand-xfer-type = "polled";

			gpmc,sync-clk-ps = <0>;
			gpmc,cs-on-ns = <0>;
			gpmc,cs-rd-off-ns = <44>;
			gpmc,cs-wr-off-ns = <44>;
			gpmc,adv-on-ns = <6>;
			gpmc,adv-rd-off-ns = <34>;
			gpmc,adv-wr-off-ns = <44>;
			gpmc,we-off-ns = <40>;
			gpmc,oe-off-ns = <54>;
			gpmc,access-ns = <64>;
			gpmc,rd-cycle-ns = <82>;
			gpmc,wr-cycle-ns = <82>;
			gpmc,wr-access-ns = <40>;
			gpmc,wr-data-mux-bus-ns = <0>;

			#address-cells = <1>;
			#size-cells = <1>;

			/* partitions go here */
		};
	};

How to select correct ECC scheme for your device ?
--------------------------------------------------
Higher ECC scheme usually means better protection against bit-flips and
increased system lifetime. However, selection of ECC scheme is dependent
on various other factors also like;

(1) support of built in hardware engines.
	Some legacy OMAP SoC do not have ELM harware engine, so those SoC cannot
	support ecc-schemes with hardware error-correction (BCHx_HW). However
	such SoC can use ecc-schemes with software library for error-correction
	(BCHx_HW_DETECTION_SW). The error correction capability with software
	library remains equivalent to their hardware counter-part, but there is
	slight CPU penalty when too many bit-flips are detected during reads.

(2) Device parameters like OOBSIZE.
	Other factor which governs the selection of ecc-scheme is oob-size.
	Higher ECC schemes require more OOB/Spare area to store ECC syndrome,
	so the device should have enough free bytes available its OOB/Spare
	area to accommodate ECC for entire page. In general following expression
	helps in determining if given device can accommodate ECC syndrome:
	"2 + (PAGESIZE / 512) * ECC_BYTES" >= OOBSIZE"
	where
		OOBSIZE		number of bytes in OOB/spare area
		PAGESIZE	number of bytes in main-area of device page
		ECC_BYTES	number of ECC bytes generated to protect
		                512 bytes of data, which is:
				'3' for HAM1_xx ecc schemes
				'7' for BCH4_xx ecc schemes
				'14' for BCH8_xx ecc schemes
				'26' for BCH16_xx ecc schemes

	Example(a): For a device with PAGESIZE = 2048 and OOBSIZE = 64 and
		trying to use BCH16 (ECC_BYTES=26) ecc-scheme.
		Number of ECC bytes per page = (2 + (2048 / 512) * 26) = 106 B
		which is greater than capacity of NAND device (OOBSIZE=64)
		Hence, BCH16 cannot be supported on given device. But it can
		probably use lower ecc-schemes like BCH8.

	Example(b): For a device with PAGESIZE = 2048 and OOBSIZE = 128 and
		trying to use BCH16 (ECC_BYTES=26) ecc-scheme.
		Number of ECC bytes per page = (2 + (2048 / 512) * 26) = 106 B
		which can be accommodated in the OOB/Spare area of this device
		(OOBSIZE=128). So this device can use BCH16 ecc-scheme.
Commit	Line	Data
bc6b1e7b DM	1	Device tree bindings for GPMC connected NANDs
	2
	3	GPMC connected NAND (found on OMAP boards) are represented as child nodes of
	4	the GPMC controller with a name of "nand".
	5
	6	All timing relevant properties as well as generic gpmc child properties are
	7	explained in a separate documents - please refer to
	8	Documentation/devicetree/bindings/bus/ti-gpmc.txt
	9
	10	For NAND specific properties such as ECC modes or bus width, please refer to
	11	Documentation/devicetree/bindings/mtd/nand.txt
	12
	13
	14	Required properties:
	15
	16	- reg: The CS line the peripheral is connected to
	17
	18	Optional properties:
	19
	20	- nand-bus-width: Set this numeric value to 16 if the hardware
	21	is wired that way. If not specified, a bus
	22	width of 8 is assumed.
	23
	24	- ti,nand-ecc-opt: A string setting the ECC layout to use. One of:
a3e83f05	25	"sw" 1-bit Hamming ecc code via software
c66d0391 PG	26	"hw" <deprecated> use "ham1" instead
	27	"hw-romcode" <deprecated> use "ham1" instead
	28	"ham1" 1-bit Hamming ecc code
bc6b1e7b DM	29	"bch4" 4-bit BCH ecc code
bc6b1e7b DM	30	"bch8" 8-bit BCH ecc code
edf02fb2	31	"bch16" 16-bit BCH ECC code
edf02fb2	32	Refer below "How to select correct ECC scheme for your device ?"
bc6b1e7b	33
496c8a0b MJ	34	- ti,nand-xfer-type: A string setting the data transfer type. One of:
	35
	36	"prefetch-polled" Prefetch polled mode (default)
	37	"polled" Polled mode, without prefetch
	38	"prefetch-dma" Prefetch enabled sDMA mode
	39	"prefetch-irq" Prefetch enabled irq mode
	40
ac65caf5 PG	41	- elm_id: <deprecated> use "ti,elm-id" instead
	42	- ti,elm-id: Specifies phandle of the ELM devicetree node.
	43	ELM is an on-chip hardware engine on TI SoC which is used for
	44	locating ECC errors for BCHx algorithms. SoC devices which have
	45	ELM hardware engines should specify this device node in .dtsi
	46	Using ELM for ECC error correction frees some CPU cycles.
97c794a1	47
c98be0c9	48	For inline partition table parsing (optional):
bc6b1e7b DM	49
	50	- #address-cells: should be set to 1
	51	- #size-cells: should be set to 1
	52
	53	Example for an AM33xx board:
	54
	55	gpmc: gpmc@50000000 {
	56	compatible = "ti,am3352-gpmc";
	57	ti,hwmods = "gpmc";
	58	reg = <0x50000000 0x1000000>;
	59	interrupts = <100>;
	60	gpmc,num-cs = <8>;
	61	gpmc,num-waitpins = <2>;
	62	#address-cells = <2>;
	63	#size-cells = <1>;
	64	ranges = <0 0 0x08000000 0x2000>; /* CS0: NAND */
97c794a1	65	elm_id = <&elm>;
bc6b1e7b DM	66
	67	nand@0,0 {
	68	reg = <0 0 0>; /* CS0, offset 0 */
	69	nand-bus-width = <16>;
	70	ti,nand-ecc-opt = "bch8";
496c8a0b	71	ti,nand-xfer-type = "polled";
bc6b1e7b	72
c059e028 JH	73	gpmc,sync-clk-ps = <0>;
	74	gpmc,cs-on-ns = <0>;
	75	gpmc,cs-rd-off-ns = <44>;
	76	gpmc,cs-wr-off-ns = <44>;
	77	gpmc,adv-on-ns = <6>;
	78	gpmc,adv-rd-off-ns = <34>;
	79	gpmc,adv-wr-off-ns = <44>;
	80	gpmc,we-off-ns = <40>;
	81	gpmc,oe-off-ns = <54>;
	82	gpmc,access-ns = <64>;
	83	gpmc,rd-cycle-ns = <82>;
	84	gpmc,wr-cycle-ns = <82>;
	85	gpmc,wr-access-ns = <40>;
	86	gpmc,wr-data-mux-bus-ns = <0>;
bc6b1e7b DM	87
	88	#address-cells = <1>;
	89	#size-cells = <1>;
	90
	91	/* partitions go here */
	92	};
	93	};
	94
edf02fb2	95	How to select correct ECC scheme for your device ?
	96	--------------------------------------------------
	97	Higher ECC scheme usually means better protection against bit-flips and
	98	increased system lifetime. However, selection of ECC scheme is dependent
	99	on various other factors also like;
	100
	101	(1) support of built in hardware engines.
	102	Some legacy OMAP SoC do not have ELM harware engine, so those SoC cannot
	103	support ecc-schemes with hardware error-correction (BCHx_HW). However
	104	such SoC can use ecc-schemes with software library for error-correction
	105	(BCHx_HW_DETECTION_SW). The error correction capability with software
	106	library remains equivalent to their hardware counter-part, but there is
	107	slight CPU penalty when too many bit-flips are detected during reads.
	108
	109	(2) Device parameters like OOBSIZE.
	110	Other factor which governs the selection of ecc-scheme is oob-size.
	111	Higher ECC schemes require more OOB/Spare area to store ECC syndrome,
	112	so the device should have enough free bytes available its OOB/Spare
24488c39 HS	113	area to accommodate ECC for entire page. In general following expression
24488c39 HS	114	helps in determining if given device can accommodate ECC syndrome:
edf02fb2	115	"2 + (PAGESIZE / 512) * ECC_BYTES" >= OOBSIZE"
	116	where
	117	OOBSIZE number of bytes in OOB/spare area
	118	PAGESIZE number of bytes in main-area of device page
	119	ECC_BYTES number of ECC bytes generated to protect
	120	512 bytes of data, which is:
	121	'3' for HAM1_xx ecc schemes
	122	'7' for BCH4_xx ecc schemes
	123	'14' for BCH8_xx ecc schemes
	124	'26' for BCH16_xx ecc schemes
	125
	126	Example(a): For a device with PAGESIZE = 2048 and OOBSIZE = 64 and
	127	trying to use BCH16 (ECC_BYTES=26) ecc-scheme.
	128	Number of ECC bytes per page = (2 + (2048 / 512) * 26) = 106 B
	129	which is greater than capacity of NAND device (OOBSIZE=64)
	130	Hence, BCH16 cannot be supported on given device. But it can
	131	probably use lower ecc-schemes like BCH8.
	132
	133	Example(b): For a device with PAGESIZE = 2048 and OOBSIZE = 128 and
	134	trying to use BCH16 (ECC_BYTES=26) ecc-scheme.
	135	Number of ECC bytes per page = (2 + (2048 / 512) * 26) = 106 B
24488c39	136	which can be accommodated in the OOB/Spare area of this device
edf02fb2	137	(OOBSIZE=128). So this device can use BCH16 ecc-scheme.