[PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Krzysztof Kozlowski]

Samsung Exynos SoCs and boards related bindings evolved since the initial
introduction, but initially the bindings were minimal and a bit incomplete
(they never described all the hardware modules available in the SoCs).
Since then some significant (not fully compatible) changes have been
already committed a few times (like gpio replaced by pinctrl, display ddc,
mfc reserved memory, some core clocks added to various hardware modules,
added more required nodes).

On the other side there are no boards which have device tree embedded in
the bootloader. Device tree blob is always compiled from the kernel tree
and updated together with the kernel image.

Thus to avoid further adding a bunch of workarounds for old/missing
bindings, make development of new platforms easier and allow to make
cleanup of the existing code and device tree files, lets mark some
Samsung Exynos SoC platform bindings as unstable. This means that
bindings can may change at any time and users should use the dtb file
compiled from the same kernel source tree as the kernel image.

Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
[krzk: Explicitly list unstable bindings instead of marking entire
Exynos]
Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>

---

Changes since v2:
1. Add tags.

Changes since v1:
1. Rebase
2. Add specific compatibles to mark unstable.

v1 is here:
https://patchwork.kernel.org/patch/9477963/

Previous tags (not applying due to change in contents):
Reviewed-by: Pankaj Dubey <pankaj.dubey@samsung.com>
---
 .../devicetree/bindings/arm/samsung/exynos.txt     | 26 ++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/samsung/exynos.txt

diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos.txt b/Documentation/devicetree/bindings/arm/samsung/exynos.txt
new file mode 100644
index 000000000000..7410cb79e4b2
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/samsung/exynos.txt
@@ -0,0 +1,26 @@
+Samsung Exynos SoC Family Device Tree Bindings
+---------------------------------------------------------------
+
+Work in progress statement:
+
+Following Device Tree files and bindings applying to Samsung Exynos SoCs and
+boards are considered "unstable":
+
+ - samsung,exynos5433* (all compatibles related to Exynos5433)
+ - samsung,exynos7* (all compatibles related to Exynos7)
+ - samsung,tm2-audio
+ - samsung,mfc-v10
+ - samsung,exynos*-mipi-dsi
+ - samsung,exynos5-dp
+ - samsung,exynos*-hdmi
+ - samsung,exynos*-hdmiddc
+ - samsung,exynos*-hdmiphy
+ - samsung,exynos*-mixer
+ - samsung,exynos*-fimd
+
+Any Samsung Exynos device tree binding mentioned may change at any time. Be
+sure to use a device tree binary and a kernel image generated from the same
+source tree.
+
+Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a
+stable binding/ABI.
-- 
2.14.1

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Andi Shyti]

Hi Krzysztof,

On Thu, Aug 30, 2018 at 08:02:05PM +0200, Krzysztof Kozlowski wrote:
> Samsung Exynos SoCs and boards related bindings evolved since the initial
> introduction, but initially the bindings were minimal and a bit incomplete
> (they never described all the hardware modules available in the SoCs).
> Since then some significant (not fully compatible) changes have been
> already committed a few times (like gpio replaced by pinctrl, display ddc,
> mfc reserved memory, some core clocks added to various hardware modules,
> added more required nodes).
> 
> On the other side there are no boards which have device tree embedded in
> the bootloader. Device tree blob is always compiled from the kernel tree
> and updated together with the kernel image.
> 
> Thus to avoid further adding a bunch of workarounds for old/missing
> bindings, make development of new platforms easier and allow to make
> cleanup of the existing code and device tree files, lets mark some
> Samsung Exynos SoC platform bindings as unstable. This means that
> bindings can may change at any time and users should use the dtb file
           ^^^^^^^
you have a typo here, other than that I agree with the patch:

Acked-by: Andi Shyti <andi@etezian.org>

Thanks,
Andi

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Krzysztof Kozlowski]

On Fri, 31 Aug 2018 at 13:18, Andi Shyti <andi@etezian.org> wrote:
>
> Hi Krzysztof,
>
> On Thu, Aug 30, 2018 at 08:02:05PM +0200, Krzysztof Kozlowski wrote:
> > Samsung Exynos SoCs and boards related bindings evolved since the initial
> > introduction, but initially the bindings were minimal and a bit incomplete
> > (they never described all the hardware modules available in the SoCs).
> > Since then some significant (not fully compatible) changes have been
> > already committed a few times (like gpio replaced by pinctrl, display ddc,
> > mfc reserved memory, some core clocks added to various hardware modules,
> > added more required nodes).
> >
> > On the other side there are no boards which have device tree embedded in
> > the bootloader. Device tree blob is always compiled from the kernel tree
> > and updated together with the kernel image.
> >
> > Thus to avoid further adding a bunch of workarounds for old/missing
> > bindings, make development of new platforms easier and allow to make
> > cleanup of the existing code and device tree files, lets mark some
> > Samsung Exynos SoC platform bindings as unstable. This means that
> > bindings can may change at any time and users should use the dtb file
>            ^^^^^^^
> you have a typo here, other than that I agree with the patch:
>
> Acked-by: Andi Shyti <andi@etezian.org>

Thanks for spotting this.

Krzysztof

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Rob Herring]

On Thu, Aug 30, 2018 at 08:02:05PM +0200, Krzysztof Kozlowski wrote:
> Samsung Exynos SoCs and boards related bindings evolved since the initial
> introduction, but initially the bindings were minimal and a bit incomplete
> (they never described all the hardware modules available in the SoCs).
> Since then some significant (not fully compatible) changes have been
> already committed a few times (like gpio replaced by pinctrl, display ddc,
> mfc reserved memory, some core clocks added to various hardware modules,
> added more required nodes).
> 
> On the other side there are no boards which have device tree embedded in
> the bootloader. Device tree blob is always compiled from the kernel tree
> and updated together with the kernel image.
> 
> Thus to avoid further adding a bunch of workarounds for old/missing
> bindings, make development of new platforms easier and allow to make
> cleanup of the existing code and device tree files, lets mark some
> Samsung Exynos SoC platform bindings as unstable. This means that
> bindings can may change at any time and users should use the dtb file
> compiled from the same kernel source tree as the kernel image.
> 
> Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
> [krzk: Explicitly list unstable bindings instead of marking entire
> Exynos]
> Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
> Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
> 
> ---
> 
> Changes since v2:
> 1. Add tags.
> 
> Changes since v1:
> 1. Rebase
> 2. Add specific compatibles to mark unstable.
> 
> v1 is here:
> https://patchwork.kernel.org/patch/9477963/
> 
> Previous tags (not applying due to change in contents):
> Reviewed-by: Pankaj Dubey <pankaj.dubey@samsung.com>
> ---
>  .../devicetree/bindings/arm/samsung/exynos.txt     | 26 ++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/arm/samsung/exynos.txt

Feel free to take this thru the Samsung tree, but don't expect an ack 
from me.

Rob

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Krzysztof Kozlowski]

On Thu, Aug 30, 2018 at 08:02:05PM +0200, Krzysztof Kozlowski wrote:
> Samsung Exynos SoCs and boards related bindings evolved since the initial
> introduction, but initially the bindings were minimal and a bit incomplete
> (they never described all the hardware modules available in the SoCs).
> Since then some significant (not fully compatible) changes have been
> already committed a few times (like gpio replaced by pinctrl, display ddc,
> mfc reserved memory, some core clocks added to various hardware modules,
> added more required nodes).
> 
> On the other side there are no boards which have device tree embedded in
> the bootloader. Device tree blob is always compiled from the kernel tree
> and updated together with the kernel image.
> 
> Thus to avoid further adding a bunch of workarounds for old/missing
> bindings, make development of new platforms easier and allow to make
> cleanup of the existing code and device tree files, lets mark some
> Samsung Exynos SoC platform bindings as unstable. This means that
> bindings can may change at any time and users should use the dtb file
> compiled from the same kernel source tree as the kernel image.
> 
> Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
> [krzk: Explicitly list unstable bindings instead of marking entire
> Exynos]
> Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
> Reviewed-by: Javier Martinez Canillas <javier@osg.samsung.com>
> Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
> 

Applied.

Best regards,
Krzysztof

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Olof Johansson]

On Thu, Aug 30, 2018 at 7:02 PM, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> Samsung Exynos SoCs and boards related bindings evolved since the initial
> introduction, but initially the bindings were minimal and a bit incomplete
> (they never described all the hardware modules available in the SoCs).
> Since then some significant (not fully compatible) changes have been
> already committed a few times (like gpio replaced by pinctrl, display ddc,
> mfc reserved memory, some core clocks added to various hardware modules,
> added more required nodes).
>
> On the other side there are no boards which have device tree embedded in
> the bootloader. Device tree blob is always compiled from the kernel tree
> and updated together with the kernel image.
>
> Thus to avoid further adding a bunch of workarounds for old/missing
> bindings, make development of new platforms easier and allow to make
> cleanup of the existing code and device tree files, lets mark some
> Samsung Exynos SoC platform bindings as unstable. This means that
> bindings can may change at any time and users should use the dtb file
> compiled from the same kernel source tree as the kernel image.

I have to admit that I don't really like this approach, and I missed
the patch when originally posted (I did notice it in the pull request
it came in with though).

The main concern for me is that with a blanket "everything is always
unstable" we discard the notion that we should strive for bindings to
be stable and backwards compatible.

Questions that come to mind are:

 - When do they stop being unstable?
 - Is there a way to note in the binding itself that it's still
unstable with an anticipation of when it will be settled in?
 - Is there a better way to version the bindings to avoid complete
backwards compatibility?

Pointing out a couple of cases where it has been painful to stay
backwards compatible could also be useful for understanding (even
though you run the risk of each case being explained away with
suggestions of how it can be handled).


-Olof

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Krzysztof Kozlowski]

On Sun, Sep 23, 2018 at 02:46:20PM +0100, Olof Johansson wrote:
> On Thu, Aug 30, 2018 at 7:02 PM, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> > Samsung Exynos SoCs and boards related bindings evolved since the initial
> > introduction, but initially the bindings were minimal and a bit incomplete
> > (they never described all the hardware modules available in the SoCs).
> > Since then some significant (not fully compatible) changes have been
> > already committed a few times (like gpio replaced by pinctrl, display ddc,
> > mfc reserved memory, some core clocks added to various hardware modules,
> > added more required nodes).
> >
> > On the other side there are no boards which have device tree embedded in
> > the bootloader. Device tree blob is always compiled from the kernel tree
> > and updated together with the kernel image.
> >
> > Thus to avoid further adding a bunch of workarounds for old/missing
> > bindings, make development of new platforms easier and allow to make
> > cleanup of the existing code and device tree files, lets mark some
> > Samsung Exynos SoC platform bindings as unstable. This means that
> > bindings can may change at any time and users should use the dtb file
> > compiled from the same kernel source tree as the kernel image.
> 
> I have to admit that I don't really like this approach, and I missed
> the patch when originally posted (I did notice it in the pull request
> it came in with though).
> 
> The main concern for me is that with a blanket "everything is always
> unstable" we discard the notion that we should strive for bindings to
> be stable and backwards compatible.

The original idea from Marek was to mark everything unstable. After
comments from Rob I made it weaker already by changing to specific group
of compatibles. Accepting their instability does not mean that we will
be doing this on whenever possible. It just opens the possibility of
finding some balance in cleanups and development. Sometimes things have
to be seriously changed (fixed) and implementing workarounds for
existing ABI might be huge work by itself.

IOW, we want stability but not with the costs of huge development
efforts... because no one else except us cares about the stability.

> 
> Questions that come to mind are:
> 
>  - When do they stop being unstable?

They became unstable in a subjective way so I assume that reverse is the
same, based on consensus and discussions.

I am not sure if a hard time limit is good. There is no timeline for the
Exynos development, no public roadmaps but rather community and
partially volountary effort.  Therefore whatever number we set, it might
be totally not matching reality.

>  - Is there a way to note in the binding itself that it's still
> unstable with an anticipation of when it will be settled in?

Hmm, I see that some existing bindings are being added with "Unstable"
warning:

	git grep -i unstable Documentation/devicetree/

so there should be no problem for putting there a timeframe.

>  - Is there a better way to version the bindings to avoid complete
> backwards compatibility?

Some architectures are using overlays for handling backward
compatibility. Anyway it might put additional effort on driver
development.

> Pointing out a couple of cases where it has been painful to stay
> backwards compatible could also be useful for understanding (even
> though you run the risk of each case being explained away with
> suggestions of how it can be handled).
> 


Best regards,
Krzysztof

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Olof Johansson]

On Mon, Sep 24, 2018 at 07:16:45PM +0200, Krzysztof Kozlowski wrote:
> On Sun, Sep 23, 2018 at 02:46:20PM +0100, Olof Johansson wrote:
> > On Thu, Aug 30, 2018 at 7:02 PM, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> > > Samsung Exynos SoCs and boards related bindings evolved since the initial
> > > introduction, but initially the bindings were minimal and a bit incomplete
> > > (they never described all the hardware modules available in the SoCs).
> > > Since then some significant (not fully compatible) changes have been
> > > already committed a few times (like gpio replaced by pinctrl, display ddc,
> > > mfc reserved memory, some core clocks added to various hardware modules,
> > > added more required nodes).
> > >
> > > On the other side there are no boards which have device tree embedded in
> > > the bootloader. Device tree blob is always compiled from the kernel tree
> > > and updated together with the kernel image.
> > >
> > > Thus to avoid further adding a bunch of workarounds for old/missing
> > > bindings, make development of new platforms easier and allow to make
> > > cleanup of the existing code and device tree files, lets mark some
> > > Samsung Exynos SoC platform bindings as unstable. This means that
> > > bindings can may change at any time and users should use the dtb file
> > > compiled from the same kernel source tree as the kernel image.
> > 
> > I have to admit that I don't really like this approach, and I missed
> > the patch when originally posted (I did notice it in the pull request
> > it came in with though).
> > 
> > The main concern for me is that with a blanket "everything is always
> > unstable" we discard the notion that we should strive for bindings to
> > be stable and backwards compatible.
> 
> The original idea from Marek was to mark everything unstable. After
> comments from Rob I made it weaker already by changing to specific group
> of compatibles. Accepting their instability does not mean that we will
> be doing this on whenever possible. It just opens the possibility of
> finding some balance in cleanups and development. Sometimes things have
> to be seriously changed (fixed) and implementing workarounds for
> existing ABI might be huge work by itself.
> 
> IOW, we want stability but not with the costs of huge development
> efforts... because no one else except us cares about the stability.

I think it's really problematic to retroactively mark a binding as unstable.
The best way to do it is probably at the time of introduction if you anticipate
it needing adjustments down the road (i.e. if it's for a complex IP block).

For major overhauls, it might be worth updating to a new binding instead (by
appending a suffix to the name or similar, and documenting that).

> > Questions that come to mind are:
> > 
> >  - When do they stop being unstable?
> 
> They became unstable in a subjective way so I assume that reverse is the
> same, based on consensus and discussions.
> 
> I am not sure if a hard time limit is good. There is no timeline for the
> Exynos development, no public roadmaps but rather community and
> partially volountary effort.  Therefore whatever number we set, it might
> be totally not matching reality.

I think that sets up for a pretty bad experience for some downstream users.

The main problem with unstable bindings is if you have a platform that you
haven't (yet) upstreamed the devicetrees for. Moving around base kernel
versions in those cases can be really awkward.

"Just upstream your devicetrees" is one counter-argument, but it's not always
that easy -- it might be unreleased products or just some experimental
platforms that might even be tracking fairly close to mainline during whatever
development is ongoing.

> >  - Is there a way to note in the binding itself that it's still
> > unstable with an anticipation of when it will be settled in?
> 
> Hmm, I see that some existing bindings are being added with "Unstable"
> warning:
> 
> 	git grep -i unstable Documentation/devicetree/
> 
> so there should be no problem for putting there a timeframe.

Yeah, adding them with unstable up front is a good way to do it (and then
remove that warning once things have settled down).

> >  - Is there a better way to version the bindings to avoid complete
> > backwards compatibility?
> 
> Some architectures are using overlays for handling backward
> compatibility. Anyway it might put additional effort on driver
> development.

In some cases it's pretty easy to stay backwards compatible by making sure
that things like missing properties have the same defaults as they used to
before the properties became mandatory.

For complex subsystems it might be a different story, but that's also where it
_might_ be worth looking at a new revision of the binding instead, this time
maybe closer to a permanent one.

> > Pointing out a couple of cases where it has been painful to stay
> > backwards compatible could also be useful for understanding (even
> > though you run the risk of each case being explained away with
> > suggestions of how it can be handled).

Marek, do you have any good examples here? Could still be useful.


-Olof

Re: [PATCH v3] dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable

[Rob Herring]

On Tue, Sep 25, 2018 at 10:55 PM Olof Johansson <olof@lixom.net> wrote:
>
> On Mon, Sep 24, 2018 at 07:16:45PM +0200, Krzysztof Kozlowski wrote:
> > On Sun, Sep 23, 2018 at 02:46:20PM +0100, Olof Johansson wrote:
> > > On Thu, Aug 30, 2018 at 7:02 PM, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> > > > Samsung Exynos SoCs and boards related bindings evolved since the initial
> > > > introduction, but initially the bindings were minimal and a bit incomplete
> > > > (they never described all the hardware modules available in the SoCs).
> > > > Since then some significant (not fully compatible) changes have been
> > > > already committed a few times (like gpio replaced by pinctrl, display ddc,
> > > > mfc reserved memory, some core clocks added to various hardware modules,
> > > > added more required nodes).
> > > >
> > > > On the other side there are no boards which have device tree embedded in
> > > > the bootloader. Device tree blob is always compiled from the kernel tree
> > > > and updated together with the kernel image.
> > > >
> > > > Thus to avoid further adding a bunch of workarounds for old/missing
> > > > bindings, make development of new platforms easier and allow to make
> > > > cleanup of the existing code and device tree files, lets mark some
> > > > Samsung Exynos SoC platform bindings as unstable. This means that
> > > > bindings can may change at any time and users should use the dtb file
> > > > compiled from the same kernel source tree as the kernel image.
> > >
> > > I have to admit that I don't really like this approach, and I missed
> > > the patch when originally posted (I did notice it in the pull request
> > > it came in with though).
> > >
> > > The main concern for me is that with a blanket "everything is always
> > > unstable" we discard the notion that we should strive for bindings to
> > > be stable and backwards compatible.
> >
> > The original idea from Marek was to mark everything unstable. After
> > comments from Rob I made it weaker already by changing to specific group
> > of compatibles. Accepting their instability does not mean that we will
> > be doing this on whenever possible. It just opens the possibility of
> > finding some balance in cleanups and development. Sometimes things have
> > to be seriously changed (fixed) and implementing workarounds for
> > existing ABI might be huge work by itself.
> >
> > IOW, we want stability but not with the costs of huge development
> > efforts... because no one else except us cares about the stability.
>
> I think it's really problematic to retroactively mark a binding as unstable.
> The best way to do it is probably at the time of introduction if you anticipate
> it needing adjustments down the road (i.e. if it's for a complex IP block).
>
> For major overhauls, it might be worth updating to a new binding instead (by
> appending a suffix to the name or similar, and documenting that).
>
> > > Questions that come to mind are:
> > >
> > >  - When do they stop being unstable?

That's my biggest issue with marking things unstable. They will never
get promoted. There's no carrot and I don't want to be the stick.

> > They became unstable in a subjective way so I assume that reverse is the
> > same, based on consensus and discussions.
> >
> > I am not sure if a hard time limit is good. There is no timeline for the
> > Exynos development, no public roadmaps but rather community and
> > partially volountary effort.  Therefore whatever number we set, it might
> > be totally not matching reality.
>
> I think that sets up for a pretty bad experience for some downstream users.

Yes, but it's the platform maintainers that should get yelled at if users care.

There's some discussion about stable/unstable DTs for EBBR[1]. The
current thought is to have an EBBR property in the DT. That would
serve as a tag that the platform DT is considered stable and something
the distros can support and rely on us not breaking.

> The main problem with unstable bindings is if you have a platform that you
> haven't (yet) upstreamed the devicetrees for. Moving around base kernel
> versions in those cases can be really awkward.
>
> "Just upstream your devicetrees" is one counter-argument, but it's not always
> that easy -- it might be unreleased products or just some experimental
> platforms that might even be tracking fairly close to mainline during whatever
> development is ongoing.
>
> > >  - Is there a way to note in the binding itself that it's still
> > > unstable with an anticipation of when it will be settled in?
> >
> > Hmm, I see that some existing bindings are being added with "Unstable"
> > warning:
> >
> >       git grep -i unstable Documentation/devicetree/
> >
> > so there should be no problem for putting there a timeframe.
>
> Yeah, adding them with unstable up front is a good way to do it (and then
> remove that warning once things have settled down).

The real question is how many have gone from unstable to stable. My guess is 0.

My preference is the default is stable (semi-stable?), but changes
that break compatibility must be documented doing so and it is up to
the platform maintainers. I don't want to see "unstable" as license to
just put anything in and have a constant churn. Extending a binding
one property at a time does not result in a good design. Then mark
platforms stable meaning no compatibility breaks and distros can count
on the stability. We could improve the documenting part as often
submitters aren't aware of the issue. I'd like to see kernel-ci do
boot tests with kernel N and DT N-1 (and perhaps N+1(-next)).

> > >  - Is there a better way to version the bindings to avoid complete
> > > backwards compatibility?
> >
> > Some architectures are using overlays for handling backward
> > compatibility. Anyway it might put additional effort on driver
> > development.
>
> In some cases it's pretty easy to stay backwards compatible by making sure
> that things like missing properties have the same defaults as they used to
> before the properties became mandatory.
>
> For complex subsystems it might be a different story, but that's also where it
> _might_ be worth looking at a new revision of the binding instead, this time
> maybe closer to a permanent one.

The distros (SUSE, at least) also care about forwards compatibility
which is harder. A common example is a platform that changes from a
bunch of fixed clocks to actual clock binding and driver. Older
kernels will be missing the clock driver the newer dtb needs. And this
case isn't even unstable bindings, it is moving from one stable
binding to another. I have some ideas on how to handle that one, but
there's probably other examples.

Rob

[1] https://github.com/ARM-software/ebbr