RE: [PATCH v2 1/4] Documentation: fsl-quadspi: Add fsl,ls2080a-dspi compatible string

[Yao Yuan]

On Wed, Jan 13, 2016 at 06:13 AM, Rob Herring wrote:
> On Mon, Jan 11, 2016 at 10:36 PM, Yao Yuan <yao.yuan@xxxxxxx> wrote:
> > On Thu, Dec 31, 2015 at 10:35PM, Yao Yuan <yao.yuan@xxxxxxx> wrote:
> >> On Wed, Dec 30, 2015 at 11:20 PM, Rob Herring wrote:
> >> > On Tue, Dec 29, 2015 at 9:17 PM, Yao Yuan <yao.yuan@xxxxxxx> wrote:
> >> > > Hi Rob,
> >> > >
> >> > > Thanks for your review.
> >> > > So you mean that I should add the commit message for why I add
> >> > > this new
> >> > compatible?
> >> >
> >> > Please don't top post on the lists.
> >> >
> >> > No, the binding doc should explain what are valid combinations of
> >> > compatible strings and the order when the dts can have multiple
> >> > strings. For example, is this valid:
> >> >
> >> > compatible = "fsl,vf610-dspi", "fsl,ls2080a-dspi";
> >> >
> >> > In other words, I should be able to check a dts file against what
> >> > the binding doc says.
> >> >
> >> > Rob
> >>
> >> OK, I got it.
> >> The "fsl,vf610-dspi", "fsl,ls1021a-v1.0-dspi", "fsl,ls2085a-dspi" is
> >> valid and used in driver.
> >> But "fsl,ls2080a-dspi" is just used for platform flag.
> >> Could you help to give an example that how can I explain it in Documents?
> >> Or should I not write this compatible in Document.
> >>
> >> I find that many compatible strings like this (not valid just a
> >> platform flag) for other driver are not record in document.
> 
> Well, things sneak in without getting documented. Also, lots of PPC bindings
> predate our documentation requirement.
> 
> >>
> >> Thanks.
> >>
> >> Yuan Yao
> >
> > Hi Rob,
> > How about like this:
> > diff --git a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
> > b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
> > index 00c587b..7a9a523 100644
> > --- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
> > +++ b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
> > @@ -4,6 +4,8 @@ Required properties:
> >    - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi",
> >                  "fsl,imx7d-qspi", "fsl,imx6ul-qspi",
> >                  "fsl,ls1021-qspi"
> > +       Invalid compatible just for SOC flag:
> > +               "fsl,ls2080a-qspi"
> 
> This doesn't make sense to me. Typically, we see something like:
> 
> Should be one of:
>   "vendor,soc1-device"
>   "vendor,soc2-device"
> Followed by "vendor,soc0-device"
> 
> Sometime the last entry is a generic string. Here soc0 is the first SOC with the
> block. Later SOCs have "the same" block, but new compatible strings in addition
> in case any changes or errata are found that the driver needs to deal with.
> 

Hi Rob,

Thanks for your suggestion,
So how about like this:
--- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
+++ b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt
@@ -2,7 +2,10 @@

 Required properties:
   - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi",
-                "fsl,imx7d-qspi", "fsl,imx6ul-qspi"
+                "fsl,imx7d-qspi", "fsl,imx6ul-qspi",
+                "fsl,ls1021a-qspi",
+                Or
+                "fsl,ls2080a-qspi" followed by "fsl,ls1021a-qspi",

But if we add addition information in binging documents, once any changes or errata are found that the driver needs to deal (such as "vendor,soc1-device"), the binging document should also be update. 
Because at that time the driver should also match "vendor,soc1-device"
So at that time we can't say "vendor,soc1-device"should followed by "vendor,soc0-device"

It seems the only benefit that may keep the dts no changes.

Thanks.
Yao