[v2,2/5] dt-bindings: display: ssd1307fb: Remove default width and height values

  A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
anymore. Instead is set to a width and height that's controller dependent.

The datasheets for the chips describes the following display resolutions:

 - SH1106:  132 x 64 Dot Matrix OLED/PLED
 - SSD1305: 132 x 64 Dot Matrix OLED/PLED
 - SSD1306: 128 x 64 Dot Matrix OLED/PLED
 - SSD1307: 128 x 39 Dot Matrix OLED/PLED
 - SSD1309: 128 x 64 Dot Matrix OLED/PLED

Update DT schema to reflect what the driver does and make its users aware.

Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>
---

Changes in v2:
- List per controller default width/height values in DT schema (Maxime Ripard).

 .../bindings/display/solomon,ssd1307fb.yaml   | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)
  

On Fri, Jun 09, 2023 at 07:09:37PM +0200, Javier Martinez Canillas wrote:
> A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
> anymore. Instead is set to a width and height that's controller dependent.

Did that change to the driver not break backwards compatibility with
existing devicetrees that relied on the default values to get 96x16?

Cheers,
Conor.

> 
> The datasheets for the chips describes the following display resolutions:
> 
>  - SH1106:  132 x 64 Dot Matrix OLED/PLED
>  - SSD1305: 132 x 64 Dot Matrix OLED/PLED
>  - SSD1306: 128 x 64 Dot Matrix OLED/PLED
>  - SSD1307: 128 x 39 Dot Matrix OLED/PLED
>  - SSD1309: 128 x 64 Dot Matrix OLED/PLED
> 
> Update DT schema to reflect what the driver does and make its users aware.
> 
> Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
> Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>
> ---
> 
> Changes in v2:
> - List per controller default width/height values in DT schema (Maxime Ripard).
> 
>  .../bindings/display/solomon,ssd1307fb.yaml   | 28 ++++++++++++++++---
>  1 file changed, 24 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml
> index 94bb5ef567c6..20e2bd15d4d2 100644
> --- a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml
> +++ b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml
> @@ -49,15 +49,15 @@ properties:
>  
>    solomon,height:
>      $ref: /schemas/types.yaml#/definitions/uint32
> -    default: 16
>      description:
> -      Height in pixel of the screen driven by the controller
> +      Height in pixel of the screen driven by the controller.
> +      The default value is controller-dependent.
>  
>    solomon,width:
>      $ref: /schemas/types.yaml#/definitions/uint32
> -    default: 96
>      description:
> -      Width in pixel of the screen driven by the controller
> +      Width in pixel of the screen driven by the controller.
> +      The default value is controller-dependent.
>  
>    solomon,page-offset:
>      $ref: /schemas/types.yaml#/definitions/uint32
> @@ -157,6 +157,10 @@ allOf:
>              const: sinowealth,sh1106
>      then:
>        properties:
> +        width:
> +          default: 132
> +        height:
> +          default: 64
>          solomon,dclk-div:
>            default: 1
>          solomon,dclk-frq:
> @@ -171,6 +175,10 @@ allOf:
>                - solomon,ssd1305
>      then:
>        properties:
> +        width:
> +          default: 132
> +        height:
> +          default: 64
>          solomon,dclk-div:
>            default: 1
>          solomon,dclk-frq:
> @@ -185,6 +193,10 @@ allOf:
>                - solomon,ssd1306
>      then:
>        properties:
> +        width:
> +          default: 128
> +        height:
> +          default: 64
>          solomon,dclk-div:
>            default: 1
>          solomon,dclk-frq:
> @@ -199,6 +211,10 @@ allOf:
>                - solomon,ssd1307
>      then:
>        properties:
> +        width:
> +          default: 128
> +        height:
> +          default: 39
>          solomon,dclk-div:
>            default: 2
>          solomon,dclk-frq:
> @@ -215,6 +231,10 @@ allOf:
>                - solomon,ssd1309
>      then:
>        properties:
> +        width:
> +          default: 128
> +        height:
> +          default: 64
>          solomon,dclk-div:
>            default: 1
>          solomon,dclk-frq:
> -- 
> 2.40.1
>
  

Conor Dooley <conor@kernel.org> writes:

> On Fri, Jun 09, 2023 at 07:09:37PM +0200, Javier Martinez Canillas wrote:
>> A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
>> anymore. Instead is set to a width and height that's controller dependent.
>
> Did that change to the driver not break backwards compatibility with
> existing devicetrees that relied on the default values to get 96x16?
>

It would but I don't think it is an issue in pratice. Most users of these
panels use one of the multiple libraries on top of the spidev interface.

For the small userbase that don't, I believe that they will use the rpif
kernel and ssd1306-overlay.dtbo DTB overlay, which defaults to width=128
and height=64 [1]. So those users will have to explicitly set a width and
height for a 96x16 panel anyways.

The intersection of users that have a 96x16 panel, assumed that default
and consider the DTB a stable ABI, and only update their kernel but not
the  DTB should be very small IMO.

[1]: https://github.com/raspberrypi/linux/blob/rpi-6.1.y/arch/arm/boot/dts/overlays/ssd1306-overlay.dts

> Cheers,
> Conor.
>
  

On Sat, Jun 10, 2023 at 07:51:35PM +0200, Javier Martinez Canillas wrote:
> Conor Dooley <conor@kernel.org> writes:
> 
> > On Fri, Jun 09, 2023 at 07:09:37PM +0200, Javier Martinez Canillas wrote:
> >> A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
> >> anymore. Instead is set to a width and height that's controller dependent.
> >
> > Did that change to the driver not break backwards compatibility with
> > existing devicetrees that relied on the default values to get 96x16?
> >
> 
> It would but I don't think it is an issue in pratice. Most users of these
> panels use one of the multiple libraries on top of the spidev interface.
> 
> For the small userbase that don't, I believe that they will use the rpif
> kernel and ssd1306-overlay.dtbo DTB overlay, which defaults to width=128
> and height=64 [1]. So those users will have to explicitly set a width and
> height for a 96x16 panel anyways.
> 
> The intersection of users that have a 96x16 panel, assumed that default
> and consider the DTB a stable ABI, and only update their kernel but not
> the  DTB should be very small IMO.

It's the adding of new defaults that makes it a bit messier, since you
can't even revert without potentially breaking a newer user. I'd be more
inclined to require the properties, rather change their defaults in the
binding, lest there are people relying on them.
If you and the other knowledgeable folk in the area really do know such
users do not exist then I suppose it is fine to do.
  

Conor Dooley <conor@kernel.org> writes:

> On Sat, Jun 10, 2023 at 07:51:35PM +0200, Javier Martinez Canillas wrote:
>> Conor Dooley <conor@kernel.org> writes:
>> 
>> > On Fri, Jun 09, 2023 at 07:09:37PM +0200, Javier Martinez Canillas wrote:
>> >> A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
>> >> anymore. Instead is set to a width and height that's controller dependent.
>> >
>> > Did that change to the driver not break backwards compatibility with
>> > existing devicetrees that relied on the default values to get 96x16?
>> >
>> 
>> It would but I don't think it is an issue in pratice. Most users of these
>> panels use one of the multiple libraries on top of the spidev interface.
>> 
>> For the small userbase that don't, I believe that they will use the rpif
>> kernel and ssd1306-overlay.dtbo DTB overlay, which defaults to width=128
>> and height=64 [1]. So those users will have to explicitly set a width and
>> height for a 96x16 panel anyways.
>> 
>> The intersection of users that have a 96x16 panel, assumed that default
>> and consider the DTB a stable ABI, and only update their kernel but not
>> the  DTB should be very small IMO.
>
> It's the adding of new defaults that makes it a bit messier, since you
> can't even revert without potentially breaking a newer user. I'd be more
> inclined to require the properties, rather change their defaults in the
> binding, lest there are people relying on them.

I think that's OK, the old drivers/video/fbdev/ssd1307fb.c fbdev driver
still has the old behaviour so it will only be a problem for users that
want to move to the new ssd130x driver as well.

By looking at the git log history, the 96x16 resolution was chosen when
the driver was merged because Maxime tested it on a CFA10036 board [1]
that has a 96x16 panel that uses an SSD1307 controller.

But as mentioned, that chip can drive up to 128x39 pixels so the maximum
makes more sense as default to me.

[1]: https://www.crystalfontz.com/product/cfa10036

> If you and the other knowledgeable folk in the area really do know such
> users do not exist then I suppose it is fine to do.

I believe is fine, since as explained above that change was only done in
the ssd130x DRM driver, not the ssd1307fb fbdev driver whose default is
still 96x16. Both drivers share the same DT binding scheme, I was asked
to do that to make it as much backward compatible as possible with the
old fbdev driver.

But I will be OK to drop the "solomon,ssd130?fb-i2c" compatible strings
from the DRM driver and only match against the new "solomon,ssd130?-i2c"
compatible strings. And add a different DT binding schema for the ssd130x
driver, if that would mean being able to fix things like the one mentioned
in this patch.

In my opinion, trying to always make the drivers backward compatible with
old DTBs only makes the drivers code more complicated for unclear benefit.

Usually this just ends being code that is neither used nor tested. Because
in practice most people update the DTBs and kernels, instead of trying to
make the DTB a stable ABI like firmware.
  

Hi

Am 11.06.23 um 01:18 schrieb Javier Martinez Canillas:
> Conor Dooley <conor@kernel.org> writes:
> 
>> On Sat, Jun 10, 2023 at 07:51:35PM +0200, Javier Martinez Canillas wrote:
>>> Conor Dooley <conor@kernel.org> writes:
>>>
>>>> On Fri, Jun 09, 2023 at 07:09:37PM +0200, Javier Martinez Canillas wrote:
>>>>> A default resolution in the ssd130x driver isn't set to an arbitrary 96x16
>>>>> anymore. Instead is set to a width and height that's controller dependent.
>>>>
>>>> Did that change to the driver not break backwards compatibility with
>>>> existing devicetrees that relied on the default values to get 96x16?
>>>>
>>>
>>> It would but I don't think it is an issue in pratice. Most users of these
>>> panels use one of the multiple libraries on top of the spidev interface.
>>>
>>> For the small userbase that don't, I believe that they will use the rpif
>>> kernel and ssd1306-overlay.dtbo DTB overlay, which defaults to width=128
>>> and height=64 [1]. So those users will have to explicitly set a width and
>>> height for a 96x16 panel anyways.
>>>
>>> The intersection of users that have a 96x16 panel, assumed that default
>>> and consider the DTB a stable ABI, and only update their kernel but not
>>> the  DTB should be very small IMO.
>>
>> It's the adding of new defaults that makes it a bit messier, since you
>> can't even revert without potentially breaking a newer user. I'd be more
>> inclined to require the properties, rather change their defaults in the
>> binding, lest there are people relying on them.
> 
> I think that's OK, the old drivers/video/fbdev/ssd1307fb.c fbdev driver
> still has the old behaviour so it will only be a problem for users that
> want to move to the new ssd130x driver as well.
> 
> By looking at the git log history, the 96x16 resolution was chosen when
> the driver was merged because Maxime tested it on a CFA10036 board [1]
> that has a 96x16 panel that uses an SSD1307 controller.
> 
> But as mentioned, that chip can drive up to 128x39 pixels so the maximum
> makes more sense as default to me.
> 
> [1]: https://www.crystalfontz.com/product/cfa10036
> 
>> If you and the other knowledgeable folk in the area really do know such
>> users do not exist then I suppose it is fine to do.
> 
> I believe is fine, since as explained above that change was only done in
> the ssd130x DRM driver, not the ssd1307fb fbdev driver whose default is
> still 96x16. Both drivers share the same DT binding scheme, I was asked
> to do that to make it as much backward compatible as possible with the
> old fbdev driver.
> 
> But I will be OK to drop the "solomon,ssd130?fb-i2c" compatible strings
> from the DRM driver and only match against the new "solomon,ssd130?-i2c"
> compatible strings. And add a different DT binding schema for the ssd130x
> driver, if that would mean being able to fix things like the one mentioned
> in this patch.
> 
> In my opinion, trying to always make the drivers backward compatible with
> old DTBs only makes the drivers code more complicated for unclear benefit.
> 
> Usually this just ends being code that is neither used nor tested. Because
> in practice most people update the DTBs and kernels, instead of trying to
> make the DTB a stable ABI like firmware.
> 

 From my understanding, fixing the resolution is the correct thing to do 
here. Userspace needs to be able to handle these differences.

Best regards
Thomas

-- 
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstrasse 146, 90461 Nuernberg, Germany
GF: Ivo Totev, Andrew Myers, Andrew McDonald, Boudien Moerman
HRB 36809 (AG Nuernberg)
  

On Mon, Jun 12, 2023 at 09:47:12AM +0200, Thomas Zimmermann wrote:
> Am 11.06.23 um 01:18 schrieb Javier Martinez Canillas:

> > But I will be OK to drop the "solomon,ssd130?fb-i2c" compatible strings
> > from the DRM driver and only match against the new "solomon,ssd130?-i2c"
> > compatible strings. And add a different DT binding schema for the ssd130x
> > driver, if that would mean being able to fix things like the one mentioned
> > in this patch.

If there are different compatibles, then it can always be sorted out
later iff it turns out to be a problem, since new devicetrees should not
be using the deprecated compatibles anyway. I didn't realise that those
deprecated compatibles existed, thanks for your patience.

> > In my opinion, trying to always make the drivers backward compatible with
> > old DTBs only makes the drivers code more complicated for unclear benefit.
> > 
> > Usually this just ends being code that is neither used nor tested. Because
> > in practice most people update the DTBs and kernels, instead of trying to
> > make the DTB a stable ABI like firmware.
> > 
> 
> From my understanding, fixing the resolution is the correct thing to do
> here. Userspace needs to be able to handle these differences.

Fixing meaning correcting, or fixing meaning using a fixed resolution?
Not clear to me what you mean, sorry.
  

Conor Dooley <conor@kernel.org> writes:

> On Mon, Jun 12, 2023 at 09:47:12AM +0200, Thomas Zimmermann wrote:
>> Am 11.06.23 um 01:18 schrieb Javier Martinez Canillas:
>
>> > But I will be OK to drop the "solomon,ssd130?fb-i2c" compatible strings
>> > from the DRM driver and only match against the new "solomon,ssd130?-i2c"
>> > compatible strings. And add a different DT binding schema for the ssd130x
>> > driver, if that would mean being able to fix things like the one mentioned
>> > in this patch.
>
> If there are different compatibles, then it can always be sorted out
> later iff it turns out to be a problem, since new devicetrees should not
> be using the deprecated compatibles anyway. I didn't realise that those
> deprecated compatibles existed, thanks for your patience.
>

No worries, thanks for raising this question.

>> > In my opinion, trying to always make the drivers backward compatible with
>> > old DTBs only makes the drivers code more complicated for unclear benefit.
>> > 
>> > Usually this just ends being code that is neither used nor tested. Because
>> > in practice most people update the DTBs and kernels, instead of trying to
>> > make the DTB a stable ABI like firmware.
>> > 
>> 
>> From my understanding, fixing the resolution is the correct thing to do
>> here. Userspace needs to be able to handle these differences.
>
> Fixing meaning correcting, or fixing meaning using a fixed resolution?
> Not clear to me what you mean, sorry.
>

Fixing meaning using as a default the correct maximum resolution for each
OLED controller, rather than an arbitrary 96x16 resolution that was added
just to be compatible with the panel that was tested the original driver.

But after talking with Thomas and Maxime about this issue, I realized that
it won't even cause an issue for theoretical users that may be relying on
the previous default.

Changing the default resolution to something smaller could cause an issue
since a user expecting a bigger default would get their display output cut
but changing to something bigger just means user-space being able to write
more pixels than those that will be displayed.

Because there isn't really a "resolution" configured in the chip, but just
how many pixels a particular controller can drive. The new default is the
maximum that each controller supports according to their documentation.