[PATCH] mtd: nand: document the NAND controller/NAND chip DT representation

[PATCH] mtd: nand: document the NAND controller/NAND chip DT representation

[Boris Brezillon]

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>
---
 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..fbf5677 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 it's 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 */
+		};
+	};
-- 
2.5.0

Re: [PATCH] mtd: nand: document the NAND controller/NAND chip DT representation

[Harvey Hunt]

Hi Boris,

On 31/03/16 14:57, Boris Brezillon wrote:
> 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>
> ---
>   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..fbf5677 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 it's own DT node, and all

s/it's/its/

> +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 */

Did you mean "chip specific properties"?

> +		};
> +	};
>

Thanks,

Harvey

Re: [PATCH] mtd: nand: document the NAND controller/NAND chip DT representation

[Boris Brezillon]

On Thu, 31 Mar 2016 16:15:26 +0100
Harvey Hunt <harvey.hunt@imgtec.com> wrote:

> Hi Boris,
> 
> On 31/03/16 14:57, Boris Brezillon wrote:
> > 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>
> > ---
> >   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..fbf5677 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 it's own DT node, and all
> 
> s/it's/its/

Yep, I'll fix that.

> 
> > +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 */
> 
> Did you mean "chip specific properties"?

No, it's really "controller specific properties". Those are properties
prefixed by the controller vendor name (like 'allwinner,rb' which is
encoding the native ready/busy pin to be attached to this chip).



-- 
Boris Brezillon, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com

Re: [PATCH] mtd: nand: document the NAND controller/NAND chip DT representation

[Harvey Hunt]

Hi,

On 31/03/16 16:19, Boris Brezillon wrote:
> On Thu, 31 Mar 2016 16:15:26 +0100
> Harvey Hunt <harvey.hunt@imgtec.com> wrote:
>
>> Hi Boris,
>>
>> On 31/03/16 14:57, Boris Brezillon wrote:
>>> 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>
>>> ---
>>>    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..fbf5677 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 it's own DT node, and all
>>
>> s/it's/its/
>
> Yep, I'll fix that.
>
>>
>>> +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 */
>>
>> Did you mean "chip specific properties"?
>
> No, it's really "controller specific properties". Those are properties
> prefixed by the controller vendor name (like 'allwinner,rb' which is
> encoding the native ready/busy pin to be attached to this chip).
>

Okay, I see - I was somewhat confused by it being in the nand chip node, 
but I understand what you mean now.

Thanks,

Harvey