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