mtd: nand: document the NAND controller/NAND chip DT representation

[Linux-MTD Mailing List]

Gitweb:     http://git.infradead.org/?p=mtd-2.6.git;a=commit;h=2d472aba15ff169a30dc3661f837d8535af9b9ee
Commit:     2d472aba15ff169a30dc3661f837d8535af9b9ee
Parent:     ce8716e97149d15379603890c4c7a2acfcf4a7ee
Author:     Boris Brezillon <boris.brezillon at free-electrons.com>
AuthorDate: Fri Apr 1 14:26:35 2016 +0200
Committer:  Boris Brezillon <boris.brezillon at free-electrons.com>
CommitDate: Tue Apr 19 22:04:51 2016 +0200

    mtd: nand: document the NAND controller/NAND chip DT representation
    
    Standardize the NAND controller/NAND chip DT representation. Now, all new
    NAND controller drivers should comply with this representation, even if
    they are only supporting a single NAND chip.
    
    Existing drivers can keep support for the old representation (where only
    the NAND chip was described), but are encouraged to also support the new
    one.
    
    Signed-off-by: Boris Brezillon <boris.brezillon at free-electrons.com>
    Acked-by: Brian Norris <computersforpeace at gmail.com>
    Acked-by: Rob Herring <robh at kernel.org>
---
 Documentation/devicetree/bindings/mtd/nand.txt | 37 +++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt
index b53f92e..a17662b 100644
--- a/Documentation/devicetree/bindings/mtd/nand.txt
+++ b/Documentation/devicetree/bindings/mtd/nand.txt
@@ -1,4 +1,23 @@
-* MTD generic binding
+* NAND chip and NAND controller generic binding
+
+NAND controller/NAND chip representation:
+
+The NAND controller should be represented with its own DT node, and all
+NAND chips attached to this controller should be defined as children nodes
+of the NAND controller. This representation should be enforced even for
+simple controllers supporting only one chip.
+
+Mandatory NAND controller properties:
+- #address-cells: depends on your controller. Should at least be 1 to
+		  encode the CS line id.
+- #size-cells: depends on your controller. Put zero unless you need a
+	       mapping between CS lines and dedicated memory regions
+
+Optional NAND controller properties
+- ranges: only needed if you need to define a mapping between CS lines and
+	  memory regions
+
+Optional NAND chip properties:
 
 - nand-ecc-mode : String, operation mode of the NAND ecc mode.
   Supported values are: "none", "soft", "hw", "hw_syndrome", "hw_oob_first",
@@ -19,3 +38,19 @@ errors per {size} bytes".
 The interpretation of these parameters is implementation-defined, so not all
 implementations must support all possible combinations. However, implementations
 are encouraged to further specify the value(s) they support.
+
+Example:
+
+	nand-controller {
+		#address-cells = <1>;
+		#size-cells = <0>;
+
+		/* controller specific properties */
+
+		nand at 0 {
+			reg = <0>;
+			nand-ecc-mode = "soft_bch";
+
+			/* controller specific properties */
+		};
+	};