dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable
Subsystems (2)
Krzysztof Kozlowski
maintainerPATCH v3 1/1 dt-bindings: arm: Explicitly mark Samsung Exynos SoC as unstable
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.
[krzk: Explicitly list unstable bindings instead of marking entire Exynos]
---
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):
--- .../devicetree/bindings/arm/samsung/exynos.txt | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/samsung/exynos.txt
Documentation/devicetree/bindings/arm/samsung/exynos.txt new file +26 -0
@@ -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.
Signature · 1 line
2.14.1
Hi Krzysztof,
Quoted 12 lines · 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.
Quoted 5 lines
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:
Thanks,
Andi
Krzysztof Kozlowski
maintainerQuoted 21 lines · Andi Shyti
Hi Krzysztof,
Quoted 12 lines · 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.
Quoted 5 lines
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
Quoted 4 lines
^^^^^^^you have a typo here, other than that I agree with the patch:
Acked-by Andi Shyti <[email protected]>
Thanks for spotting this.
Krzysztof
Rob Herring
maintainerQuoted 38 lines · 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 <[email protected]>[krzk: Explicitly list unstable bindings instead of marking entire Exynos]
Signed-off-by Krzysztof Kozlowski <[email protected]>Reviewed-by Javier Martinez Canillas <[email protected]>---
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/
Quoted 6 lines
Previous tags (not applying due to change in contents):
Reviewed-by Pankaj Dubey <[email protected]>--- .../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
Quoted 19 lines · 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.
Quoted 7 lines
Signed-off-by Marek Szyprowski <[email protected]>[krzk: Explicitly list unstable bindings instead of marking entire Exynos]
Signed-off-by Krzysztof Kozlowski <[email protected]>Reviewed-by Javier Martinez Canillas <[email protected]>
Applied.
Best regards,
Krzysztof
Quoted 12 lines · 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.
Quoted 6 lines
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
Krzysztof Kozlowski
maintainerQuoted 20 lines · Olof Johansson
Quoted 12 lines · 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.
Quoted 6 lines
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.
Quoted 7 lines
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.
Quoted 4 lines
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.
Quoted 2 lines
- 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.
Quoted 2 lines
- 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.
Quoted 5 lines
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
Quoted 37 lines · Krzysztof Kozlowski
Quoted 20 lines · Olof Johansson
Quoted 12 lines · 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.
Quoted 6 lines
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.
Quoted 7 lines
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.
Quoted 2 lines
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).
Quoted 11 lines
Quoted 3 lines
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.
Quoted 9 lines
Quoted 2 lines
- 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).
Quoted 6 lines
Quoted 2 lines
- 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.
Quoted 4 lines
Quoted 4 lines
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
Quoted 42 lines · Olof Johansson
Quoted 37 lines · Krzysztof Kozlowski
Quoted 20 lines · Olof Johansson
Quoted 12 lines · 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.
Quoted 6 lines
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.
Quoted 7 lines
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.
Quoted 2 lines
IOW, we want stability but not with the costs of huge development efforts... because no one else except us cares about the stability.
Quoted 10 lines
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).
Quoted 3 lines
Quoted 3 lines
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.
Quoted 9 lines
Quoted 7 lines
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.
Quoted 15 lines
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.
Quoted 6 lines
Quoted 2 lines
- 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:
Quoted 6 lines
Quoted 3 lines
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)).
Quoted 7 lines
Quoted 6 lines
Quoted 2 lines
- 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.
Quoted 7 lines
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