[PATCH v1 2/2] mtd: docg3: add device-tree documentation

[Mark Rutland]

On Fri, Sep 26, 2014 at 06:19:49PM +0100, Robert Jarzmik wrote:
> Mark Rutland <mark.rutland at arm.com> writes:
> 
> >> +The Sandisk (former MSystems) docg3 is a nand device of 64M to 256MB.
> >
> > I think that should be: "(formerly M-Systems)".
> Right.
> 
> > I'd rather we used the full name (DiskOnChip G3), as "docg3" is a
> > Linux-specific abbreviation. So I think the compatible string should be
> > something like "sandisk,diskonchip-g3". Arguably we should have
> > M-Systems as the vendor.
> "sandisk,diskonchip-g3" : full ack, for v2

ok.

> For M-Systems, it's as you wish. Just so that you have the broad view, this is
> my understanding of M-Systems / Sandisk :
>  - M-Systems creates several diskonchip chips, especially docg3

Ok, so I'd label those devices with an M-Systems vendor prefix
("m-systems", I guess, if we don't already have one).

>  - M-Systems is bought and absorbed by Sandisk

For the devices sold during this time where nothing has changed other
than the label, I'd keep the M-Systems vendor.

>  - Sandisk creates and ships other diskonchip, under sandisk brand

These new devices I would label with a sandisk vendor-prefix.

> Now I'll put in the compat whatever you advice for, I have no opinion on
> that. I'm telling you this because I have another patch to submit for a camera
> sensor made by Aptina. Aptina was absorbed by Micron, and the sensor was
> released under Aptina/Micron brand (ie. Aptina team in Micron corp. if I
> understood correctly).
> 
> Therefore, I'll take your advice for both sandisk/msystems and aptina/micron :)

I'd label something as the original brand it shipped under, unless
there's a compelling reason not to. We can add notes in the binding
documentation to make the bindings easier to find where a device has
been labelled by different manufacturers.

> > Are we able to detect the particular variant by reading registers on the
> > device? Are there any differences that we can probe dynamically (even if
> > we don't care about those at the moment)?
> 
> Yes, what defines a docg3 is :
>  - a device mapped at address 0
>  - a read of the chip id gives DOC_CHIPID_G3
> 
> But there is a catch : the read is not a simple memory read, it's a write to a
> register to set the "register to read", then a read in the iospace. Doing this
> implies you know you are in the iospace of a docg3 ...

I was more concerned with the identifying information that we can
acquire from the device than the precise sequence of steps that have to
be performed to extract that information.

You mention that the size of the flash is variable (it could be 64MB,
256MB, etc), but this isn't described in the binding. Therefore I assume
there is some mechanism by which I can query this from the device?

Are there other parameters that vary across instances? Even those for
which we currently don't care? If so, can these be queried from the
device?

> >
> >> +
> >> +Required properties:
> >> + - compatible: Should be "sandisk,docg3"
> >> + - reg: register base and size
> >> +
> >> +Example:
> >> +	docg3 {
> >> +		compatible = "sandisk,docg3";
> >> +		reg = <0x0 0x2000>;
> >
> > There should be a unit-address on the node to match the address in the
> > first reg entry.
> You mean "#address-cells = <1>;", right ?

No, the unit-address is the bit after the '@' on the node name. I'm
asking for:

docg3: flash at 0 {
	...
	reg = <0x0 0x2000>;
	...
};

Thanks,
Mark.