Subject: Re: [PATCH net-next 1/8] Documentation/bindings: net: ocelot: document the PTP bank

From: Antoine Tenart <[email-masked]>
Date: Fri, 5 Jul 2019 18:39:29 +0200

Hi Andrew,

On Fri, Jul 05, 2019 at 04:45:17PM +0200, Andrew Lunn wrote:
> On Fri, Jul 05, 2019 at 03:30:16PM +0200, Antoine Tenart wrote:
> > 
> > I'm not sure about this: optional properties means some parts of the h/w
> > can be missing or not wired. It's not the case here, it's "optional" in
> > the driver only for dt compatibility (so that an older dt blob can work
> > with a newer kernel image), but it's now mandatory in the binding.
> 
> If the driver can work without it, it is clearly optional. You just
> get reduced functionality. That is the thing with DT. You can never
> add more required properties after the first commit without breaking
> backwards compatibility. To make the documentation fit the driver,
> somewhere you need to state they are optional. Either by placing the
> new properties in the optional section of the binding, or add a
> comment.

The documentation is unrelated to the driver. It's the documentation of
the binding itself, which is only describing the h/w.

But I discussed this with a someone and I got to the same conclusion as
your statement, because there can be old dt blobs in the wild and the
binding documentation can be used to make new code. That code should be
aware of required/optional properties.

I'll fix this in v2.

Thanks!
Antoine

-- 
Antoine Ténart, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com