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@free-electrons.com>
Acked-by: Brian Norris <computersforpeace@gmail.com>
Acked-by: Rob Herring <robh@kernel.org>

diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt
index b53f92e252d4a7f48427ca1e123381dc04e91e41..a17662b1dfcb9d1ef4e0c6d110eedefe6b8a294d 100644 (file)
--- 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@0 {
+                       reg = <0>;
+                       nand-ecc-mode = "soft_bch";
+
+                       /* controller specific properties */
+               };
+       };