Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Scott Wood]

On 08/09/2011 01:45 PM, Robin Holt wrote:
> On Tue, Aug 09, 2011 at 01:17:47PM -0500, Scott Wood wrote:
>> On 08/09/2011 09:43 AM, Robin Holt wrote:
>>> In working with the socketcan developers, we have come to the conclusion
>>> the fsl-flexcan device tree bindings need to be cleaned up. 
>>> The driver does not depend upon any properties other than the required properties
>>> so we are removing the file.
>>
>> That is not the criterion for whether something should be expresed in
>> the device tree.  It's a description of the hardware, not a Linux driver
>> configuration file.  If there are integration parameters that can not be
>> inferred from "this is FSL flexcan v1.0", they should be expressed in
>> the node.
> 
> There are no properties other than the required properties.  The others
> were wrongly introduced and are not needed by the driver.

Not needed by this driver, or will never be needed by any reasonable
driver (or is not a good description of the hardware)?

The device tree is not an internal Linux implementation detail.  It is
shared by other OSes, firmwares, hypervisors, etc.  Bindings should be
created with care, and kept stable unless there's a good reason to break
compatibility.

devicetree-discuss@lists.ozlabs.org should be CCed on device tree
discussions.

> When we
> removed the other properties and the wrong documentation of the mscan
> oscillator source in the fsl-flexcan.txt file, we were left with an
> Example: section and a one-line statement "The only properties supported
> are the required properties."  That seemed like the fsl-flexcan.txt
> file was then pointless.

There is the compatible string, and you could mention that there is a
single reg resource and a single interrupt.

>> Removing the binding altogether seems extreme as well -- we should have
>> bindings for all devices, even if there are no special properties.
> 
> Ok.  I can do that too.  Who is the definitive source for that answer?

For policy questions on device tree bindings?  Grant Likely is the
maintainer for device tree stuff.

A lot of the simpler bindings have been left undocumented so far, IMHO
it should be a goal to document them all.  There are some existing ones
that are documented despite not having special properties, e.g.
Documentation/devicetree/bindings/serio/altera_ps2.txt,
Documentation/devicetree/bindings/arm/sirf.txt,
Documentation/devicetree/bindings/powerpc/nintendo/wii.txt, etc.

> I assume we are talking about the fsl-flexcan.txt file when we say
> binding.  Is that correct?

Yes, although devicetree.org is another possibility.

>>> Additionally, the p1010*dts files are not
>>> following the standard for node naming in that they have a trailing -v1.0.
>>
>> What "standard for node naming"?  There's nothing wrong with putting a
> 
> For the answer to that, you will need to ask Wolfgang Grandegger.  I was
> working from his feedback.  Looking at the plethora of other node names,
> the vast majority do not have any -v#.#, and the ones that do also tend
> to have multiple versions. Based upon that, I suspect he is correct,
> but I do not know where the documentation is or if it even exists.

There's a lot of crap in old bindings, plus it's not appropriate for all
circumstances (specifying bindings should be done a little more
carefully than "what do most other bindings do?").  It's something we've
been doing lately for blocks that have a version number, but it's not
dynamically readable.

Looking in the FlexCAN chapter of the p1010 manual, I don't see any
reference to a block version, and I do see references to "previous
FlexCAN versions".  So I suggest "fsl,p1010-flexcan".

-Scott

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Wolfgang Grandegger]

On 08/09/2011 09:13 PM, Scott Wood wrote:
> On 08/09/2011 01:45 PM, Robin Holt wrote:
>> On Tue, Aug 09, 2011 at 01:17:47PM -0500, Scott Wood wrote:
>>> On 08/09/2011 09:43 AM, Robin Holt wrote:
>>>> In working with the socketcan developers, we have come to the conclusion
>>>> the fsl-flexcan device tree bindings need to be cleaned up. 
>>>> The driver does not depend upon any properties other than the required properties
>>>> so we are removing the file.
>>>
>>> That is not the criterion for whether something should be expresed in
>>> the device tree.  It's a description of the hardware, not a Linux driver
>>> configuration file.  If there are integration parameters that can not be
>>> inferred from "this is FSL flexcan v1.0", they should be expressed in
>>> the node.
>>
>> There are no properties other than the required properties.  The others
>> were wrongly introduced and are not needed by the driver.
> 
> Not needed by this driver, or will never be needed by any reasonable
> driver (or is not a good description of the hardware)?
> 
> The device tree is not an internal Linux implementation detail.  It is
> shared by other OSes, firmwares, hypervisors, etc.  Bindings should be
> created with care, and kept stable unless there's a good reason to break
> compatibility.
> 
> devicetree-discuss-uLR06cmDAlY/bJ5BZ2RsiQ@public.gmane.org should be CCed on device tree
> discussions.

Yes. The doc for the bindings we speak about

http://lxr.linux.no/#linux+v3.0.1/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt

sneaked into the kernel without been presented on any mailing list and
without the corresponding driver patch.

>> When we
>> removed the other properties and the wrong documentation of the mscan
>> oscillator source in the fsl-flexcan.txt file, we were left with an
>> Example: section and a one-line statement "The only properties supported
>> are the required properties."  That seemed like the fsl-flexcan.txt
>> file was then pointless.
> 
> There is the compatible string, and you could mention that there is a
> single reg resource and a single interrupt.
> 
>>> Removing the binding altogether seems extreme as well -- we should have
>>> bindings for all devices, even if there are no special properties.
>>
>> Ok.  I can do that too.  Who is the definitive source for that answer?
> 
> For policy questions on device tree bindings?  Grant Likely is the
> maintainer for device tree stuff.
> 
> A lot of the simpler bindings have been left undocumented so far, IMHO
> it should be a goal to document them all.  There are some existing ones
> that are documented despite not having special properties, e.g.
> Documentation/devicetree/bindings/serio/altera_ps2.txt,
> Documentation/devicetree/bindings/arm/sirf.txt,
> Documentation/devicetree/bindings/powerpc/nintendo/wii.txt, etc.
> 
>> I assume we are talking about the fsl-flexcan.txt file when we say
>> binding.  Is that correct?
> 
> Yes, although devicetree.org is another possibility.
> 
>>>> Additionally, the p1010*dts files are not
>>>> following the standard for node naming in that they have a trailing -v1.0.
>>>
>>> What "standard for node naming"?  There's nothing wrong with putting a
>>
>> For the answer to that, you will need to ask Wolfgang Grandegger.  I was
>> working from his feedback.  Looking at the plethora of other node names,
>> the vast majority do not have any -v#.#, and the ones that do also tend
>> to have multiple versions. Based upon that, I suspect he is correct,
>> but I do not know where the documentation is or if it even exists.
> 
> There's a lot of crap in old bindings, plus it's not appropriate for all
> circumstances (specifying bindings should be done a little more
> carefully than "what do most other bindings do?").  It's something we've
> been doing lately for blocks that have a version number, but it's not
> dynamically readable.
> 
> Looking in the FlexCAN chapter of the p1010 manual, I don't see any
> reference to a block version, and I do see references to "previous
> FlexCAN versions".  So I suggest "fsl,p1010-flexcan".

OK, just

  "fsl,p1010-flexcan"

or

  "fsl,p1010-flexcan", "fsl,flexcan"


Note that the Flexcan is used on Freescale ARM cores as well (and device
tree for ARM will show up soon).

Wolfgang.

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Scott Wood]

On 08/09/2011 02:49 PM, Wolfgang Grandegger wrote:
> Yes. The doc for the bindings we speak about
> 
> http://lxr.linux.no/#linux+v3.0.1/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
> 
> sneaked into the kernel without been presented on any mailing list and
> without the corresponding driver patch.

It was posted on linuxppc-dev:
http://patchwork.ozlabs.org/patch/91980/

Though I agree it should have been posted more widely.

> OK, just
> 
>   "fsl,p1010-flexcan"
> 
> or
> 
>   "fsl,p1010-flexcan", "fsl,flexcan"

I'm ok with the latter, if there's enough in common that it's
conceivable that a driver wouldn't care.  The more specific compatible
will be there if the driver wants to make use of it later.

-Scot

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Robin Holt]

I guess my poor wording may have gotten me in trouble.  I am getting
ready to repost this patch, but I want to ensure I am getting it as
right as possible.

I think I should reword the commit message to indicate we are removing
the Documentation/.../fsl-flexcan.txt file which has essentially become
empty and change the p1010si.dtsi file's can nodes to "fsl,p1010-flexcan",
"fsl,flexcan".  Is that correct?

Thanks,
Robin

On Tue, Aug 09, 2011 at 02:58:56PM -0500, Scott Wood wrote:
> On 08/09/2011 02:49 PM, Wolfgang Grandegger wrote:
> > Yes. The doc for the bindings we speak about
> > 
> > http://lxr.linux.no/#linux+v3.0.1/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
> > 
> > sneaked into the kernel without been presented on any mailing list and
> > without the corresponding driver patch.
> 
> It was posted on linuxppc-dev:
> http://patchwork.ozlabs.org/patch/91980/
> 
> Though I agree it should have been posted more widely.
> 
> > OK, just
> > 
> >   "fsl,p1010-flexcan"
> > 
> > or
> > 
> >   "fsl,p1010-flexcan", "fsl,flexcan"
> 
> I'm ok with the latter, if there's enough in common that it's
> conceivable that a driver wouldn't care.  The more specific compatible
> will be there if the driver wants to make use of it later.
> 
> -Scot

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Kumar Gala]

On Aug 9, 2011, at 3:59 PM, Robin Holt wrote:

> I guess my poor wording may have gotten me in trouble.  I am getting
> ready to repost this patch, but I want to ensure I am getting it as
> right as possible.
> 
> I think I should reword the commit message to indicate we are removing
> the Documentation/.../fsl-flexcan.txt file which has essentially become
> empty and change the p1010si.dtsi file's can nodes to "fsl,p1010-flexcan",
> "fsl,flexcan".  Is that correct?
> 
> Thanks,
> Robin

This is wrong.  Again, what binding covers "fsl,flexcan" if you remove fsl-flexcan.txt:

[galak@right powerpc]$ git grep flexcan Documentation/devicetree/bindings
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:fsl,flexcan-v1.0 nodes
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:- fsl,flexcan-clock-source : CAN Engine Clock Source.This property selects
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:- fsl,flexcan-clock-divider : for the reference and system clock, an additional
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:      - v1.0 of flexcan-v1.0 represent the IP block version for P1010 SOC.
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              compatible = "fsl,flexcan-v1.0";
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              fsl,flexcan-clock-source = "platform";
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              fsl,flexcan-clock-divider = <2>;

Not seeing anything that covers it.

I think the issue should be resolved by patching fsl-flexcan.txt to remove wording or update it.

- k

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Robin Holt]

On Wed, Aug 10, 2011 at 09:52:07AM -0500, Kumar Gala wrote:
> 
> On Aug 9, 2011, at 3:59 PM, Robin Holt wrote:
> 
> > I guess my poor wording may have gotten me in trouble.  I am getting
> > ready to repost this patch, but I want to ensure I am getting it as
> > right as possible.
> > 
> > I think I should reword the commit message to indicate we are removing
> > the Documentation/.../fsl-flexcan.txt file which has essentially become
> > empty and change the p1010si.dtsi file's can nodes to "fsl,p1010-flexcan",
> > "fsl,flexcan".  Is that correct?
> > 
> > Thanks,
> > Robin
> 
> This is wrong.  Again, what binding covers "fsl,flexcan" if you remove fsl-flexcan.txt:
> 
> [galak@right powerpc]$ git grep flexcan Documentation/devicetree/bindings
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:fsl,flexcan-v1.0 nodes
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:- fsl,flexcan-clock-source : CAN Engine Clock Source.This property selects
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:- fsl,flexcan-clock-divider : for the reference and system clock, an additional
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:      - v1.0 of flexcan-v1.0 represent the IP block version for P1010 SOC.
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              compatible = "fsl,flexcan-v1.0";
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              fsl,flexcan-clock-source = "platform";
> Documentation/devicetree/bindings/net/can/fsl-flexcan.txt:              fsl,flexcan-clock-divider = <2>;
> 
> Not seeing anything that covers it.
> 
> I think the issue should be resolved by patching fsl-flexcan.txt to remove wording or update it.

Done.

Robin

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Wolfgang Grandegger]

On 08/09/2011 08:17 PM, Scott Wood wrote:
> On 08/09/2011 09:43 AM, Robin Holt wrote:
>> In working with the socketcan developers, we have come to the conclusion
>> the fsl-flexcan device tree bindings need to be cleaned up. 
>> The driver does not depend upon any properties other than the required properties
>> so we are removing the file.
> 
> That is not the criterion for whether something should be expresed in
> the device tree.  It's a description of the hardware, not a Linux driver
> configuration file.  If there are integration parameters that can not be
> inferred from "this is FSL flexcan v1.0", they should be expressed in
> the node.
> 
> Removing the binding altogether seems extreme as well -- we should have
> bindings for all devices, even if there are no special properties.

Yes, of course. The commit message misleading. We do not intend to
remove the binding but just a few unused and confusing properties.
Concerning the compatible string, Freescale introduced for the Flexcan
on the P1010 "fsl,flexcan-v1.0". That's not the usual convention also
because the v1.0 if for the PowerPC cores only, I assume, but we have
ARM cores as well. If we need to distinguish I think we should use:

  "fsl,p1010-flexcan", "fsl,flexcan"

Do you agree?

>> Additionally, the p1010*dts files are not
>> following the standard for node naming in that they have a trailing -v1.0.
> 
> What "standard for node naming"?  There's nothing wrong with putting a
> block version number in the compatible string, and it looks like the
> p1010 dts files were following the binding document in this regard.  It
> is common practice when the block version is publicly documented but
> there's no register it can be read from at runtime.

See above.

Furthermore I must admit, that the bindings shown up mainline Linux have
never been presented on any mailing list.

Wolfgang.

Re: [PATCH 5/5] [powerpc] Fix up fsl-flexcan device tree binding.

[Scott Wood]

On 08/09/2011 02:32 PM, Wolfgang Grandegger wrote:
> On 08/09/2011 08:17 PM, Scott Wood wrote:
>> On 08/09/2011 09:43 AM, Robin Holt wrote:
>>> In working with the socketcan developers, we have come to the conclusion
>>> the fsl-flexcan device tree bindings need to be cleaned up. 
>>> The driver does not depend upon any properties other than the required properties
>>> so we are removing the file.
>>
>> That is not the criterion for whether something should be expresed in
>> the device tree.  It's a description of the hardware, not a Linux driver
>> configuration file.  If there are integration parameters that can not be
>> inferred from "this is FSL flexcan v1.0", they should be expressed in
>> the node.
>>
>> Removing the binding altogether seems extreme as well -- we should have
>> bindings for all devices, even if there are no special properties.
> 
> Yes, of course. The commit message misleading. We do not intend to
> remove the binding but just a few unused and confusing properties.

Is it a matter of the current driver not caring, or the properties just
not making sense for any reasonable driver (ambiguous, inferrable from
the flexcan version, software configuration, etc)?

-Scott