[v2,2/6] dt-bindings: pwm: amlogic: add new compatible for meson8 pwm type

  Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.

The previous clock bindings for these SoCs described the driver and not the
HW itself. The clock provided was used to set the parent of the input clock
mux among the possible parents hard-coded in the driver.

The new bindings allows to describe the actual clock inputs of the PWM in
DT, like most bindings do, instead of relying of hard-coded data.

The new bindings make the old one deprecated.

There is enough experience on this HW to know that the PWM is exactly the
same all the supported SoCs. There is no need for a per-SoC compatible.

Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
---
 .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)
  

On Fri, 17 Nov 2023 13:59:12 +0100, Jerome Brunet wrote:
> Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.
> 
> The previous clock bindings for these SoCs described the driver and not the
> HW itself. The clock provided was used to set the parent of the input clock
> mux among the possible parents hard-coded in the driver.
> 
> The new bindings allows to describe the actual clock inputs of the PWM in
> DT, like most bindings do, instead of relying of hard-coded data.
> 
> The new bindings make the old one deprecated.
> 
> There is enough experience on this HW to know that the PWM is exactly the
> same all the supported SoCs. There is no need for a per-SoC compatible.
> 
> Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
> ---
>  .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>  1 file changed, 34 insertions(+), 2 deletions(-)
> 

Reviewed-by: Rob Herring <robh@kernel.org>
  

Hi Rob,

On 19/11/2023 17:05, Rob Herring wrote:
> 
> On Fri, 17 Nov 2023 13:59:12 +0100, Jerome Brunet wrote:
>> Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.
>>
>> The previous clock bindings for these SoCs described the driver and not the
>> HW itself. The clock provided was used to set the parent of the input clock
>> mux among the possible parents hard-coded in the driver.
>>
>> The new bindings allows to describe the actual clock inputs of the PWM in
>> DT, like most bindings do, instead of relying of hard-coded data.
>>
>> The new bindings make the old one deprecated.
>>
>> There is enough experience on this HW to know that the PWM is exactly the
>> same all the supported SoCs. There is no need for a per-SoC compatible.
>>
>> Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
>> ---
>>   .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>   1 file changed, 34 insertions(+), 2 deletions(-)
>>
> 
> Reviewed-by: Rob Herring <robh@kernel.org>
> 

I'm puzzled, isn't it recommended to have a per-soc compatible now ?

I thought something like:
- items:
     - enum:
         - amlogic,gxbb-pwm
         - amlogic,axg-pwm
         - amlogic,g12a-pwm
     - const: amlogic,pwm-v1

should be preferred instead of a single amlogic,meson8-pwm-v2 ?

Neil
  

On Mon 20 Nov 2023 at 09:27, Neil Armstrong <neil.armstrong@linaro.org> wrote:

> Hi Rob,
>
> On 19/11/2023 17:05, Rob Herring wrote:
>> On Fri, 17 Nov 2023 13:59:12 +0100, Jerome Brunet wrote:
>>> Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.
>>>
>>> The previous clock bindings for these SoCs described the driver and not the
>>> HW itself. The clock provided was used to set the parent of the input clock
>>> mux among the possible parents hard-coded in the driver.
>>>
>>> The new bindings allows to describe the actual clock inputs of the PWM in
>>> DT, like most bindings do, instead of relying of hard-coded data.
>>>
>>> The new bindings make the old one deprecated.
>>>
>>> There is enough experience on this HW to know that the PWM is exactly the
>>> same all the supported SoCs. There is no need for a per-SoC compatible.
>>>
>>> Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
>>> ---
>>>   .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>   1 file changed, 34 insertions(+), 2 deletions(-)
>>>
>> Reviewed-by: Rob Herring <robh@kernel.org>
>> 
>
> I'm puzzled, isn't it recommended to have a per-soc compatible now ?

I have specifically addressed this matter in the description,
haven't I ? What good would it do in this case ?

Plus the definition of a SoC is very vague. One could argue that
the content of the list bellow are vaguely defined families. Should we
add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
This list gets huge for no reason.

We know all existing PWM of this type are the same. We have been using
them for years. It is not a new support we know nothing about.

>
> I thought something like:
> - items:
>     - enum:
>         - amlogic,gxbb-pwm
>         - amlogic,axg-pwm
>         - amlogic,g12a-pwm
>     - const: amlogic,pwm-v1

I'm not sure I understand what you are suggesting here.
Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
has that and I'm working to remove this type, so I don't get the point.

>
> should be preferred instead of a single amlogic,meson8-pwm-v2 ?

This is named after the first SoC supporting the type.

Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
Plus the doc specifically advise against this type of names.

>
> Neil
  

Hi Jerome,

On 20/11/2023 10:18, Jerome Brunet wrote:
> 
> On Mon 20 Nov 2023 at 09:27, Neil Armstrong <neil.armstrong@linaro.org> wrote:
> 
>> Hi Rob,
>>
>> On 19/11/2023 17:05, Rob Herring wrote:
>>> On Fri, 17 Nov 2023 13:59:12 +0100, Jerome Brunet wrote:
>>>> Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.
>>>>
>>>> The previous clock bindings for these SoCs described the driver and not the
>>>> HW itself. The clock provided was used to set the parent of the input clock
>>>> mux among the possible parents hard-coded in the driver.
>>>>
>>>> The new bindings allows to describe the actual clock inputs of the PWM in
>>>> DT, like most bindings do, instead of relying of hard-coded data.
>>>>
>>>> The new bindings make the old one deprecated.
>>>>
>>>> There is enough experience on this HW to know that the PWM is exactly the
>>>> same all the supported SoCs. There is no need for a per-SoC compatible.
>>>>
>>>> Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
>>>> ---
>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>
>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>
>>
>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
> 
> I have specifically addressed this matter in the description,
> haven't I ? What good would it do in this case ?

Yes you did but I was asked for the last year+ that all new compatible
should be soc specific (while imprecise, in our care soc family should be ok),
with a possible semi-generic callback with an IP version or a first soc
implementing the IP.

> 
> Plus the definition of a SoC is very vague. One could argue that
> the content of the list bellow are vaguely defined families. Should we
> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
> This list gets huge for no reason.

I think in our case soc family is reasonable since they share same silicon
design.

> 
> We know all existing PWM of this type are the same. We have been using
> them for years. It is not a new support we know nothing about.
> 
>>
>> I thought something like:
>> - items:
>>      - enum:
>>          - amlogic,gxbb-pwm
>>          - amlogic,axg-pwm
>>          - amlogic,g12a-pwm
>>      - const: amlogic,pwm-v1
> 
> I'm not sure I understand what you are suggesting here.
> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
> has that and I'm working to remove this type, so I don't get the point.
> 
>>
>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
> 
> This is named after the first SoC supporting the type.
> 
> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
> Plus the doc specifically advise against this type of names.

The -v2 refers to a pure software/dt implementation versioning and not
an HW version, so I'm puzzled and I requires DT maintainers advice here.

Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has
the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
reasonable and s4 and later pwm could use the "amlogic,pwm-v2" fallback.

Neil
> 
>>
>> Neil
>
  

On Mon 20 Nov 2023 at 10:55, neil.armstrong@linaro.org wrote:

> Hi Jerome,
>
> On 20/11/2023 10:18, Jerome Brunet wrote:
>> On Mon 20 Nov 2023 at 09:27, Neil Armstrong <neil.armstrong@linaro.org>
>> wrote:
>> 
>>> Hi Rob,
>>>
>>> On 19/11/2023 17:05, Rob Herring wrote:
>>>> On Fri, 17 Nov 2023 13:59:12 +0100, Jerome Brunet wrote:
>>>>> Add a new compatible for the pwm found in the meson8 to sm1 Amlogic SoCs.
>>>>>
>>>>> The previous clock bindings for these SoCs described the driver and not the
>>>>> HW itself. The clock provided was used to set the parent of the input clock
>>>>> mux among the possible parents hard-coded in the driver.
>>>>>
>>>>> The new bindings allows to describe the actual clock inputs of the PWM in
>>>>> DT, like most bindings do, instead of relying of hard-coded data.
>>>>>
>>>>> The new bindings make the old one deprecated.
>>>>>
>>>>> There is enough experience on this HW to know that the PWM is exactly the
>>>>> same all the supported SoCs. There is no need for a per-SoC compatible.
>>>>>
>>>>> Signed-off-by: Jerome Brunet <jbrunet@baylibre.com>
>>>>> ---
>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>
>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>
>>>
>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
>> I have specifically addressed this matter in the description,
>> haven't I ? What good would it do in this case ?
>
> Yes you did but I was asked for the last year+ that all new compatible
> should be soc specific (while imprecise, in our care soc family should be ok),
> with a possible semi-generic callback with an IP version or a first soc
> implementing the IP.
>
>> Plus the definition of a SoC is very vague. One could argue that
>> the content of the list bellow are vaguely defined families. Should we
>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>> This list gets huge for no reason.
>
> I think in our case soc family is reasonable since they share same silicon
> design.
>
>> We know all existing PWM of this type are the same. We have been using
>> them for years. It is not a new support we know nothing about.
>> 
>>>
>>> I thought something like:
>>> - items:
>>>      - enum:
>>>          - amlogic,gxbb-pwm
>>>          - amlogic,axg-pwm
>>>          - amlogic,g12a-pwm
>>>      - const: amlogic,pwm-v1
>> I'm not sure I understand what you are suggesting here.
>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>> has that and I'm working to remove this type, so I don't get the point.
>> 
>>>
>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>> This is named after the first SoC supporting the type.
>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>> Plus the doc specifically advise against this type of names.
>
> The -v2 refers to a pure software/dt implementation versioning and not
> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>
> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has

This is not my point. I picked this name because I have to pick a
specific device based one. Not because it is actually the first or
not. I don't see a problem with meson6 being compatible with
meson8-pwm-v2, if that ever comes along.

I think the binding here satisfy the rule that it should be specific,
and the intent that goes with it:

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42

> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
> fallback.

That is not how understand this:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82

>
> Neil
>> 
>>>
>>> Neil
>>
  

On 20/11/2023 11:04, Jerome Brunet wrote:
>>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>>
>>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>>
>>>>
>>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?

Yes, it is.

>>> I have specifically addressed this matter in the description,
>>> haven't I ? What good would it do in this case ?

There is nothing about compatible naming in commit msg.

>>
>> Yes you did but I was asked for the last year+ that all new compatible
>> should be soc specific (while imprecise, in our care soc family should be ok),
>> with a possible semi-generic callback with an IP version or a first soc
>> implementing the IP.
>>
>>> Plus the definition of a SoC is very vague. One could argue that
>>> the content of the list bellow are vaguely defined families. Should we
>>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>>> This list gets huge for no reason.
>>
>> I think in our case soc family is reasonable since they share same silicon
>> design.
>>
>>> We know all existing PWM of this type are the same. We have been using
>>> them for years. It is not a new support we know nothing about.
>>>
>>>>
>>>> I thought something like:
>>>> - items:
>>>>      - enum:
>>>>          - amlogic,gxbb-pwm
>>>>          - amlogic,axg-pwm
>>>>          - amlogic,g12a-pwm
>>>>      - const: amlogic,pwm-v1
>>> I'm not sure I understand what you are suggesting here.
>>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>>> has that and I'm working to remove this type, so I don't get the point.
>>>
>>>>
>>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>>> This is named after the first SoC supporting the type.
>>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>>> Plus the doc specifically advise against this type of names.
>>
>> The -v2 refers to a pure software/dt implementation versioning and not
>> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>>
>> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has

Yes, this should be SoC-based compatible, unless you have clear
versioning scheme by SoC/IP block vendor. You named it not a HW version,
which kind of answers to the "unless" case - that's not hardware version.

> 
> This is not my point. I picked this name because I have to pick a
> specific device based one. Not because it is actually the first or
> not. I don't see a problem with meson6 being compatible with
> meson8-pwm-v2, if that ever comes along.

No, the point is not to use "v2". Use SoC compatibles.

> 
> I think the binding here satisfy the rule that it should be specific,
> and the intent that goes with it:
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42
> 
>> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
>> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
>> fallback.
> 
> That is not how understand this:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82
> 

Again, where the "v2" is defined? Where is any document explaining the
mapping between version blocks and SoC parts? Why do you list here only
major version? Blocks almost always have also minor (e.g. v2.0).

Best regards,
Krzysztof
  

On Wed 22 Nov 2023 at 09:37, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:

> On 20/11/2023 11:04, Jerome Brunet wrote:
>>>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>>>
>>>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>>>
>>>>>
>>>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
>
> Yes, it is.
>
>>>> I have specifically addressed this matter in the description,
>>>> haven't I ? What good would it do in this case ?
>
> There is nothing about compatible naming in commit msg.

Krzysztof, the whole commit desciption is explanation about why a new
compatible is introduced. I don't understand this comment.

>
>>>
>>> Yes you did but I was asked for the last year+ that all new compatible
>>> should be soc specific (while imprecise, in our care soc family should be ok),
>>> with a possible semi-generic callback with an IP version or a first soc
>>> implementing the IP.
>>>
>>>> Plus the definition of a SoC is very vague. One could argue that
>>>> the content of the list bellow are vaguely defined families. Should we
>>>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>>>> This list gets huge for no reason.
>>>
>>> I think in our case soc family is reasonable since they share same silicon
>>> design.
>>>
>>>> We know all existing PWM of this type are the same. We have been using
>>>> them for years. It is not a new support we know nothing about.
>>>>
>>>>>
>>>>> I thought something like:
>>>>> - items:
>>>>>      - enum:
>>>>>          - amlogic,gxbb-pwm
>>>>>          - amlogic,axg-pwm
>>>>>          - amlogic,g12a-pwm
>>>>>      - const: amlogic,pwm-v1
>>>> I'm not sure I understand what you are suggesting here.
>>>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>>>> has that and I'm working to remove this type, so I don't get the point.
>>>>
>>>>>
>>>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>>>> This is named after the first SoC supporting the type.
>>>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>>>> Plus the doc specifically advise against this type of names.
>>>
>>> The -v2 refers to a pure software/dt implementation versioning and not
>>> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>>>
>>> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has
>
> Yes, this should be SoC-based compatible, unless you have clear
> versioning scheme by SoC/IP block vendor. You named it not a HW version,
> which kind of answers to the "unless" case - that's not hardware version.
>

This is specifically the point of the comment in commit description.
We know all the PWMs compatible are the same HW (version) as one found
in the meson8b.

It is certain that adding more compatible, listing all the SoC, will be
useless. I can do it if you insist.

>> 
>> This is not my point. I picked this name because I have to pick a
>> specific device based one. Not because it is actually the first or
>> not. I don't see a problem with meson6 being compatible with
>> meson8-pwm-v2, if that ever comes along.
>
> No, the point is not to use "v2". Use SoC compatibles.

It is a SoC compatible. The second one.

The first one, as explained in the description was describing the driver
more that the HW.

Changing the way clock are passed from DT to the driver would be break
user of the old compatible. So a new compatible is introduced. I believe
this is recommended way to introduce incompatible binding changes.

v2 here denote a new interface version, nothing to do with HW
versioning. I happy to pick something else to denote this.

>
>> 
>> I think the binding here satisfy the rule that it should be specific,
>> and the intent that goes with it:
>> 
>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42
>> 
>>> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
>>> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
>>> fallback.
>> 
>> That is not how understand this:
>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82
>> 
>
> Again, where the "v2" is defined? Where is any document explaining the
> mapping between version blocks and SoC parts? Why do you list here only
> major version? Blocks almost always have also minor (e.g. v2.0).

Again, v2 does has nothing to do with the HW. Never wrote it was.
The HW remains the same.


>
> Best regards,
> Krzysztof
  

On 22/11/2023 15:34, Jerome Brunet wrote:
> 
> On Wed 22 Nov 2023 at 09:37, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
> 
>> On 20/11/2023 11:04, Jerome Brunet wrote:
>>>>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>>>>
>>>>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>>>>
>>>>>>
>>>>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
>>
>> Yes, it is.
>>
>>>>> I have specifically addressed this matter in the description,
>>>>> haven't I ? What good would it do in this case ?
>>
>> There is nothing about compatible naming in commit msg.
> 
> Krzysztof, the whole commit desciption is explanation about why a new
> compatible is introduced. I don't understand this comment.
> 
>>
>>>>
>>>> Yes you did but I was asked for the last year+ that all new compatible
>>>> should be soc specific (while imprecise, in our care soc family should be ok),
>>>> with a possible semi-generic callback with an IP version or a first soc
>>>> implementing the IP.
>>>>
>>>>> Plus the definition of a SoC is very vague. One could argue that
>>>>> the content of the list bellow are vaguely defined families. Should we
>>>>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>>>>> This list gets huge for no reason.
>>>>
>>>> I think in our case soc family is reasonable since they share same silicon
>>>> design.
>>>>
>>>>> We know all existing PWM of this type are the same. We have been using
>>>>> them for years. It is not a new support we know nothing about.
>>>>>
>>>>>>
>>>>>> I thought something like:
>>>>>> - items:
>>>>>>      - enum:
>>>>>>          - amlogic,gxbb-pwm
>>>>>>          - amlogic,axg-pwm
>>>>>>          - amlogic,g12a-pwm
>>>>>>      - const: amlogic,pwm-v1
>>>>> I'm not sure I understand what you are suggesting here.
>>>>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>>>>> has that and I'm working to remove this type, so I don't get the point.
>>>>>
>>>>>>
>>>>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>>>>> This is named after the first SoC supporting the type.
>>>>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>>>>> Plus the doc specifically advise against this type of names.
>>>>
>>>> The -v2 refers to a pure software/dt implementation versioning and not
>>>> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>>>>
>>>> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has
>>
>> Yes, this should be SoC-based compatible, unless you have clear
>> versioning scheme by SoC/IP block vendor. You named it not a HW version,
>> which kind of answers to the "unless" case - that's not hardware version.
>>
> 
> This is specifically the point of the comment in commit description.
> We know all the PWMs compatible are the same HW (version) as one found
> in the meson8b.
> 
> It is certain that adding more compatible, listing all the SoC, will be
> useless. I can do it if you insist.

The docs you references insist on that, so yeah, I insist as well.

> 
>>>
>>> This is not my point. I picked this name because I have to pick a
>>> specific device based one. Not because it is actually the first or
>>> not. I don't see a problem with meson6 being compatible with
>>> meson8-pwm-v2, if that ever comes along.
>>
>> No, the point is not to use "v2". Use SoC compatibles.
> 
> It is a SoC compatible. The second one.

"v2" is not the soc. I assume meson8 is one specific SoC, right? Because
elinux says it is a *family*:
https://elinux.org/Amlogic/SoCs


> 
> The first one, as explained in the description was describing the driver
> more that the HW.
> 
> Changing the way clock are passed from DT to the driver would be break
> user of the old compatible. So a new compatible is introduced. I believe
> this is recommended way to introduce incompatible binding changes.

The way is not to introduce incompatible changes. Your way is also not
good as it breaks other users of DTS.

> 
> v2 here denote a new interface version, nothing to do with HW
> versioning. I happy to pick something else to denote this.

Sorry, then it is not a SoC-based compatible.

> 
>>
>>>
>>> I think the binding here satisfy the rule that it should be specific,
>>> and the intent that goes with it:
>>>
>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42
>>>
>>>> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
>>>> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
>>>> fallback.
>>>
>>> That is not how understand this:
>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82
>>>
>>
>> Again, where the "v2" is defined? Where is any document explaining the
>> mapping between version blocks and SoC parts? Why do you list here only
>> major version? Blocks almost always have also minor (e.g. v2.0).
> 
> Again, v2 does has nothing to do with the HW. Never wrote it was.
> The HW remains the same.

Don't add compatibles which are not related to HW, but represent
software versioning. Software does not matter for the bindings.

That's a clear NAK.

Best regards,
Krzysztof
  

On Wed 22 Nov 2023 at 16:04, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:

> On 22/11/2023 15:34, Jerome Brunet wrote:
>> 
>> On Wed 22 Nov 2023 at 09:37, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>> 
>>> On 20/11/2023 11:04, Jerome Brunet wrote:
>>>>>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>>>>>
>>>>>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>>>>>
>>>>>>>
>>>>>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
>>>
>>> Yes, it is.
>>>
>>>>>> I have specifically addressed this matter in the description,
>>>>>> haven't I ? What good would it do in this case ?
>>>
>>> There is nothing about compatible naming in commit msg.
>> 
>> Krzysztof, the whole commit desciption is explanation about why a new
>> compatible is introduced. I don't understand this comment.
>> 
>>>
>>>>>
>>>>> Yes you did but I was asked for the last year+ that all new compatible
>>>>> should be soc specific (while imprecise, in our care soc family should be ok),
>>>>> with a possible semi-generic callback with an IP version or a first soc
>>>>> implementing the IP.
>>>>>
>>>>>> Plus the definition of a SoC is very vague. One could argue that
>>>>>> the content of the list bellow are vaguely defined families. Should we
>>>>>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>>>>>> This list gets huge for no reason.
>>>>>
>>>>> I think in our case soc family is reasonable since they share same silicon
>>>>> design.
>>>>>
>>>>>> We know all existing PWM of this type are the same. We have been using
>>>>>> them for years. It is not a new support we know nothing about.
>>>>>>
>>>>>>>
>>>>>>> I thought something like:
>>>>>>> - items:
>>>>>>>      - enum:
>>>>>>>          - amlogic,gxbb-pwm
>>>>>>>          - amlogic,axg-pwm
>>>>>>>          - amlogic,g12a-pwm
>>>>>>>      - const: amlogic,pwm-v1
>>>>>> I'm not sure I understand what you are suggesting here.
>>>>>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>>>>>> has that and I'm working to remove this type, so I don't get the point.
>>>>>>
>>>>>>>
>>>>>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>>>>>> This is named after the first SoC supporting the type.
>>>>>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>>>>>> Plus the doc specifically advise against this type of names.
>>>>>
>>>>> The -v2 refers to a pure software/dt implementation versioning and not
>>>>> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>>>>>
>>>>> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has
>>>
>>> Yes, this should be SoC-based compatible, unless you have clear
>>> versioning scheme by SoC/IP block vendor. You named it not a HW version,
>>> which kind of answers to the "unless" case - that's not hardware version.
>>>
>> 
>> This is specifically the point of the comment in commit description.
>> We know all the PWMs compatible are the same HW (version) as one found
>> in the meson8b.
>> 
>> It is certain that adding more compatible, listing all the SoC, will be
>> useless. I can do it if you insist.
>
> The docs you references insist on that, so yeah, I insist as well.
>
>> 
>>>>
>>>> This is not my point. I picked this name because I have to pick a
>>>> specific device based one. Not because it is actually the first or
>>>> not. I don't see a problem with meson6 being compatible with
>>>> meson8-pwm-v2, if that ever comes along.
>>>
>>> No, the point is not to use "v2". Use SoC compatibles.
>> 
>> It is a SoC compatible. The second one.
>
> "v2" is not the soc. I assume meson8 is one specific SoC, right? Because
> elinux says it is a *family*:
> https://elinux.org/Amlogic/SoCs
>

It is a family. yes

>
>> 
>> The first one, as explained in the description was describing the driver
>> more that the HW.
>> 
>> Changing the way clock are passed from DT to the driver would be break
>> user of the old compatible. So a new compatible is introduced. I believe
>> this is recommended way to introduce incompatible binding changes.
>
> The way is not to introduce incompatible changes. Your way is also not
> good as it breaks other users of DTS.
>
>> 
>> v2 here denote a new interface version, nothing to do with HW
>> versioning. I happy to pick something else to denote this.
>
> Sorry, then it is not a SoC-based compatible.
>
>> 
>>>
>>>>
>>>> I think the binding here satisfy the rule that it should be specific,
>>>> and the intent that goes with it:
>>>>
>>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42
>>>>
>>>>> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
>>>>> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
>>>>> fallback.
>>>>
>>>> That is not how understand this:
>>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82
>>>>
>>>
>>> Again, where the "v2" is defined? Where is any document explaining the
>>> mapping between version blocks and SoC parts? Why do you list here only
>>> major version? Blocks almost always have also minor (e.g. v2.0).
>> 
>> Again, v2 does has nothing to do with the HW. Never wrote it was.
>> The HW remains the same.
>
> Don't add compatibles which are not related to HW, but represent
> software versioning. Software does not matter for the bindings.

What I did I explicitly what is recommended in Grant's presentation from
2013. 10y old, but I assume slide 10 "Making an incompatible update" is
still valid.

https://elinux.org/images/1/1e/DT_Binding_Process_glikely_ksummit_2013_10_28.pdf

Breaking the ABI of the old compatible would break all boards which use
u-boot DT and pass it to the kernel, because the meaning of the clock
property would change.

Doing things has suggested in this slide, and this patch, allows every
device to continue to work properly, whether the DT given is the one
shipped with u-boot (using the old compatible for now) or the kernel.

>
> That's a clear NAK.
>
> Best regards,
> Krzysztof
  

On 22/11/2023 16:23, Jerome Brunet wrote:
> 
> On Wed 22 Nov 2023 at 16:04, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
> 
>> On 22/11/2023 15:34, Jerome Brunet wrote:
>>>
>>> On Wed 22 Nov 2023 at 09:37, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
>>>
>>>> On 20/11/2023 11:04, Jerome Brunet wrote:
>>>>>>>>>>    .../devicetree/bindings/pwm/pwm-amlogic.yaml  | 36 +++++++++++++++++--
>>>>>>>>>>    1 file changed, 34 insertions(+), 2 deletions(-)
>>>>>>>>>>
>>>>>>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>>>>>>>
>>>>>>>>
>>>>>>>> I'm puzzled, isn't it recommended to have a per-soc compatible now ?
>>>>
>>>> Yes, it is.
>>>>
>>>>>>> I have specifically addressed this matter in the description,
>>>>>>> haven't I ? What good would it do in this case ?
>>>>
>>>> There is nothing about compatible naming in commit msg.
>>>
>>> Krzysztof, the whole commit desciption is explanation about why a new
>>> compatible is introduced. I don't understand this comment.
>>>
>>>>
>>>>>>
>>>>>> Yes you did but I was asked for the last year+ that all new compatible
>>>>>> should be soc specific (while imprecise, in our care soc family should be ok),
>>>>>> with a possible semi-generic callback with an IP version or a first soc
>>>>>> implementing the IP.
>>>>>>
>>>>>>> Plus the definition of a SoC is very vague. One could argue that
>>>>>>> the content of the list bellow are vaguely defined families. Should we
>>>>>>> add meson8b, gxl, gxm, sm1 ? ... or even the actual SoC reference ?
>>>>>>> This list gets huge for no reason.
>>>>>>
>>>>>> I think in our case soc family is reasonable since they share same silicon
>>>>>> design.
>>>>>>
>>>>>>> We know all existing PWM of this type are the same. We have been using
>>>>>>> them for years. It is not a new support we know nothing about.
>>>>>>>
>>>>>>>>
>>>>>>>> I thought something like:
>>>>>>>> - items:
>>>>>>>>      - enum:
>>>>>>>>          - amlogic,gxbb-pwm
>>>>>>>>          - amlogic,axg-pwm
>>>>>>>>          - amlogic,g12a-pwm
>>>>>>>>      - const: amlogic,pwm-v1
>>>>>>> I'm not sure I understand what you are suggesting here.
>>>>>>> Adding a "amlogic,pwm-v1" for the obsolete compatible ? No amlogic DT
>>>>>>> has that and I'm working to remove this type, so I don't get the point.
>>>>>>>
>>>>>>>>
>>>>>>>> should be preferred instead of a single amlogic,meson8-pwm-v2 ?
>>>>>>> This is named after the first SoC supporting the type.
>>>>>>> Naming it amlogic,pwm-v2 would feel weird with the s4 coming after.
>>>>>>> Plus the doc specifically advise against this type of names.
>>>>>>
>>>>>> The -v2 refers to a pure software/dt implementation versioning and not
>>>>>> an HW version, so I'm puzzled and I requires DT maintainers advice here.
>>>>>>
>>>>>> Yes meson8b is the first "known" platform, even if I'm pretty sure meson6 has
>>>>
>>>> Yes, this should be SoC-based compatible, unless you have clear
>>>> versioning scheme by SoC/IP block vendor. You named it not a HW version,
>>>> which kind of answers to the "unless" case - that's not hardware version.
>>>>
>>>
>>> This is specifically the point of the comment in commit description.
>>> We know all the PWMs compatible are the same HW (version) as one found
>>> in the meson8b.
>>>
>>> It is certain that adding more compatible, listing all the SoC, will be
>>> useless. I can do it if you insist.
>>
>> The docs you references insist on that, so yeah, I insist as well.
>>
>>>
>>>>>
>>>>> This is not my point. I picked this name because I have to pick a
>>>>> specific device based one. Not because it is actually the first or
>>>>> not. I don't see a problem with meson6 being compatible with
>>>>> meson8-pwm-v2, if that ever comes along.
>>>>
>>>> No, the point is not to use "v2". Use SoC compatibles.
>>>
>>> It is a SoC compatible. The second one.
>>
>> "v2" is not the soc. I assume meson8 is one specific SoC, right? Because
>> elinux says it is a *family*:
>> https://elinux.org/Amlogic/SoCs
>>
> 
> It is a family. yes
> 
>>
>>>
>>> The first one, as explained in the description was describing the driver
>>> more that the HW.
>>>
>>> Changing the way clock are passed from DT to the driver would be break
>>> user of the old compatible. So a new compatible is introduced. I believe
>>> this is recommended way to introduce incompatible binding changes.
>>
>> The way is not to introduce incompatible changes. Your way is also not
>> good as it breaks other users of DTS.
>>
>>>
>>> v2 here denote a new interface version, nothing to do with HW
>>> versioning. I happy to pick something else to denote this.
>>
>> Sorry, then it is not a SoC-based compatible.
>>
>>>
>>>>
>>>>>
>>>>> I think the binding here satisfy the rule that it should be specific,
>>>>> and the intent that goes with it:
>>>>>
>>>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n42
>>>>>
>>>>>> the same pwm architecture, this is why "amlogic,pwm-v1" as fallback seems more
>>>>>> reasonable and s4 and later pwm could use the "amlogic,pwm-v2"
>>>>>> fallback.
>>>>>
>>>>> That is not how understand this:
>>>>> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/writing-bindings.rst?h=v6.7-rc2#n82
>>>>>
>>>>
>>>> Again, where the "v2" is defined? Where is any document explaining the
>>>> mapping between version blocks and SoC parts? Why do you list here only
>>>> major version? Blocks almost always have also minor (e.g. v2.0).
>>>
>>> Again, v2 does has nothing to do with the HW. Never wrote it was.
>>> The HW remains the same.
>>
>> Don't add compatibles which are not related to HW, but represent
>> software versioning. Software does not matter for the bindings.
> 
> What I did I explicitly what is recommended in Grant's presentation from
> 2013. 10y old, but I assume slide 10 "Making an incompatible update" is
> still valid.
> 
> https://elinux.org/images/1/1e/DT_Binding_Process_glikely_ksummit_2013_10_28.pdf
> 
> Breaking the ABI of the old compatible would break all boards which use
> u-boot DT and pass it to the kernel, because the meaning of the clock
> property would change.

You broke U-Boot now as well - it will get your new DTS from the kernel
and stop working.

> 
> Doing things has suggested in this slide, and this patch, allows every
> device to continue to work properly, whether the DT given is the one
> shipped with u-boot (using the old compatible for now) or the kernel.

OK, that explains the reasons. I read your commit msg and nothing like
this was mentioned there. What's more, you did not deprecate the old
binding, thus the confusion - it looked like you add entirely new
hardware (although you put "deprecated" but in some unrelated place, not
next to the compatibles).

Anyway, the main point of Neil was that you started using generic
compatible for all SoCs, which is wrong as well. I guess this was the
original discussion.

Best regards,
Krzysztof
  

On Wed 22 Nov 2023 at 16:46, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:


>>>>>
>>>>> Again, where the "v2" is defined? Where is any document explaining the
>>>>> mapping between version blocks and SoC parts? Why do you list here only
>>>>> major version? Blocks almost always have also minor (e.g. v2.0).
>>>>
>>>> Again, v2 does has nothing to do with the HW. Never wrote it was.
>>>> The HW remains the same.
>>>
>>> Don't add compatibles which are not related to HW, but represent
>>> software versioning. Software does not matter for the bindings.
>> 
>> What I did I explicitly what is recommended in Grant's presentation from
>> 2013. 10y old, but I assume slide 10 "Making an incompatible update" is
>> still valid.
>> 
>> https://elinux.org/images/1/1e/DT_Binding_Process_glikely_ksummit_2013_10_28.pdf
>> 
>> Breaking the ABI of the old compatible would break all boards which use
>> u-boot DT and pass it to the kernel, because the meaning of the clock
>> property would change.
>
> You broke U-Boot now as well - it will get your new DTS from the kernel
> and stop working.

U-boot will continue to match the old compatible and work properly.
When the dts using the new compatible lands in u-boot, it won't
match until proper driver support is added. It is a lot better than
breaking the ABI, which would have silently broke u-boot.

I don't really see a way around that.

If you have better way to fix a bad interface, feel free to share it.

>
>> 
>> Doing things has suggested in this slide, and this patch, allows every
>> device to continue to work properly, whether the DT given is the one
>> shipped with u-boot (using the old compatible for now) or the kernel.
>
> OK, that explains the reasons. I read your commit msg and nothing like
> this was mentioned there. What's more, you did not deprecate the old
> binding, thus the confusion - it looked like you add entirely new
> hardware (although you put "deprecated" but in some unrelated place, not
> next to the compatibles).

The old interface being obsoleted by the new one is mentionned in the
commit description, the comments in the bindings and the bindings itself.
Thanks a lot for pointing out the placement mistake. I'll fix it.

The commit description says:
* What the patch does
* Why it does it:
  * Why the old bindings is bad/broken
  * How the new ones fixes the problem
* Why a single compatible properly describes, IMO, all the related HW.

This describes the entirety of what the change does.
That seemed clear enough for Rob. If that is not enough for you and you
would like it reworded, could please provide a few suggestions ?

>
> Anyway, the main point of Neil was that you started using generic
> compatible for all SoCs, which is wrong as well. I guess this was the
> original discussion.

The whole reason for this change is to properly describe the HW, which
is the 100% same on all the SoCs, or SoC families, concerned. The only
reason there was a lot of old compatibles is because it was used to match
data in the driver (this is clearly wrong). This data would now be
passed through DT.

I have been clear about this in the change description.

So why is it wrong to have single compatible for a type of device that
is 100% the same HW ?

It is lot a easier to apply a rule correctly when the intent is clear.

>
> Best regards,
> Krzysztof
  

On 22/11/2023 17:14, Jerome Brunet wrote:
> 
> On Wed 22 Nov 2023 at 16:46, Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> wrote:
> 
> 
>>>>>>
>>>>>> Again, where the "v2" is defined? Where is any document explaining the
>>>>>> mapping between version blocks and SoC parts? Why do you list here only
>>>>>> major version? Blocks almost always have also minor (e.g. v2.0).
>>>>>
>>>>> Again, v2 does has nothing to do with the HW. Never wrote it was.
>>>>> The HW remains the same.
>>>>
>>>> Don't add compatibles which are not related to HW, but represent
>>>> software versioning. Software does not matter for the bindings.
>>>
>>> What I did I explicitly what is recommended in Grant's presentation from
>>> 2013. 10y old, but I assume slide 10 "Making an incompatible update" is
>>> still valid.
>>>
>>> https://elinux.org/images/1/1e/DT_Binding_Process_glikely_ksummit_2013_10_28.pdf
>>>
>>> Breaking the ABI of the old compatible would break all boards which use
>>> u-boot DT and pass it to the kernel, because the meaning of the clock
>>> property would change.
>>
>> You broke U-Boot now as well - it will get your new DTS from the kernel
>> and stop working.
> 
> U-boot will continue to match the old compatible and work properly.
> When the dts using the new compatible lands in u-boot, it won't
> match until proper driver support is added. It is a lot better than
> breaking the ABI, which would have silently broke u-boot.
> 
> I don't really see a way around that.
> 
> If you have better way to fix a bad interface, feel free to share it.
> 
>>
>>>
>>> Doing things has suggested in this slide, and this patch, allows every
>>> device to continue to work properly, whether the DT given is the one
>>> shipped with u-boot (using the old compatible for now) or the kernel.
>>
>> OK, that explains the reasons. I read your commit msg and nothing like
>> this was mentioned there. What's more, you did not deprecate the old
>> binding, thus the confusion - it looked like you add entirely new
>> hardware (although you put "deprecated" but in some unrelated place, not
>> next to the compatibles).
> 
> The old interface being obsoleted by the new one is mentionned in the
> commit description, the comments in the bindings and the bindings itself.
> Thanks a lot for pointing out the placement mistake. I'll fix it.
> 
> The commit description says:
> * What the patch does
> * Why it does it:
>   * Why the old bindings is bad/broken
>   * How the new ones fixes the problem
> * Why a single compatible properly describes, IMO, all the related HW.
> 
> This describes the entirety of what the change does.
> That seemed clear enough for Rob. If that is not enough for you and you
> would like it reworded, could please provide a few suggestions ?

You did not deprecate the compatibles, so this has to be fixed. You put
the compatible in some other place, not really relevant.

> 
>>
>> Anyway, the main point of Neil was that you started using generic
>> compatible for all SoCs, which is wrong as well. I guess this was the
>> original discussion.
> 
> The whole reason for this change is to properly describe the HW, which
> is the 100% same on all the SoCs, or SoC families, concerned. The only

You still need specific compatibles, because the hardware is not 100%
the same. Programming model can, but hardware differs. Many times
engineers thought that devices are 100% compatible and then turned out
they are not. I am bored to repeat all this again and again.

> reason there was a lot of old compatibles is because it was used to match
> data in the driver (this is clearly wrong). This data would now be
> passed through DT.
> 
> I have been clear about this in the change description.
> 
> So why is it wrong to have single compatible for a type of device that
> is 100% the same HW ?

Because it is generic, not specific (you match "foo" against "bar" SoC).
The chapter from writing-bindings you referenced earlier mentioned this.
You need ability to add quirks and customize for these minor hardware
differences, even if programming model is the same.

> 
> It is lot a easier to apply a rule correctly when the intent is clear.
> 
>>
>> Best regards,
>> Krzysztof
> 

Best regards,
Krzysztof