[v2] dt-bindings: i2c: Move i2c-omap.txt to YAML format

Convert i2c-omap.txt to YAML schema for better checks and documentation.

Following properties were used in DT but were not documented in txt
bindings and has been included in YAML schema:
1. Include ti,am4372-i2c compatible
2. Include dmas property used in few OMAP dts files
3. Document clocks property

Signed-off-by: Vignesh Raghavendra <vigneshr@ti.com>
---
v2:
Fix issues with make dt_bindings_check
Add description on usage of ti,hwmods

 .../devicetree/bindings/i2c/i2c-omap.txt      | 37 ---------
 .../devicetree/bindings/i2c/ti,omap4-i2c.yaml | 80 +++++++++++++++++++
 2 files changed, 80 insertions(+), 37 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/i2c/i2c-omap.txt
 create mode 100644 Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml

On 06/05/2021 17:00, Vignesh Raghavendra wrote:
> Convert i2c-omap.txt to YAML schema for better checks and documentation.
> 
> Following properties were used in DT but were not documented in txt
> bindings and has been included in YAML schema:
> 1. Include ti,am4372-i2c compatible
> 2. Include dmas property used in few OMAP dts files

The DMA is not supported by i2c-omap driver, so wouldn't be better to just drop dmas from DTBs to avoid confusions?
It can be added later.

> 3. Document clocks property
> 
> Signed-off-by: Vignesh Raghavendra <vigneshr@ti.com>
> ---
> v2:
> Fix issues with make dt_bindings_check
> Add description on usage of ti,hwmods
> 
>   .../devicetree/bindings/i2c/i2c-omap.txt      | 37 ---------
>   .../devicetree/bindings/i2c/ti,omap4-i2c.yaml | 80 +++++++++++++++++++
>   2 files changed, 80 insertions(+), 37 deletions(-)
>   delete mode 100644 Documentation/devicetree/bindings/i2c/i2c-omap.txt
>   create mode 100644 Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
> 
> diff --git a/Documentation/devicetree/bindings/i2c/i2c-omap.txt b/Documentation/devicetree/bindings/i2c/i2c-omap.txt
> deleted file mode 100644
> index a425b91af48f..000000000000
> --- a/Documentation/devicetree/bindings/i2c/i2c-omap.txt
> +++ /dev/null
> @@ -1,37 +0,0 @@
> -I2C for OMAP platforms
> -
> -Required properties :
> -- compatible : Must be
> -	"ti,omap2420-i2c" for OMAP2420 SoCs
> -	"ti,omap2430-i2c" for OMAP2430 SoCs
> -	"ti,omap3-i2c" for OMAP3 SoCs
> -	"ti,omap4-i2c" for OMAP4+ SoCs
> -	"ti,am654-i2c", "ti,omap4-i2c" for AM654 SoCs
> -	"ti,j721e-i2c", "ti,omap4-i2c" for J721E SoCs
> -	"ti,am64-i2c", "ti,omap4-i2c" for AM64 SoCs
> -- ti,hwmods : Must be "i2c<n>", n being the instance number (1-based)
> -- #address-cells = <1>;
> -- #size-cells = <0>;
> -
> -Recommended properties :
> -- clock-frequency : Desired I2C bus clock frequency in Hz. Otherwise
> -  the default 100 kHz frequency will be used.
> -
> -Optional properties:
> -- Child nodes conforming to i2c bus binding
> -
> -Note: Current implementation will fetch base address, irq and dma
> -from omap hwmod data base during device registration.
> -Future plan is to migrate hwmod data base contents into device tree
> -blob so that, all the required data will be used from device tree dts
> -file.
> -
> -Examples :
> -
> -i2c1: i2c@0 {
> -    compatible = "ti,omap3-i2c";
> -    #address-cells = <1>;
> -    #size-cells = <0>;
> -    ti,hwmods = "i2c1";
> -    clock-frequency = <400000>;
> -};
> diff --git a/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
> new file mode 100644
> index 000000000000..eb11e3025b37
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/i2c/ti,omap4-i2c.yaml
> @@ -0,0 +1,80 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/i2c/ti,omap4-i2c.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Bindings for I2C controllers on TI's OMAP and K3 SoCs
> +
> +maintainers:
> +  - Vignesh Raghavendra <vigneshr@ti.com>
> +
> +allOf:
> +  - $ref: /schemas/i2c/i2c-controller.yaml#
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - const: ti,omap2420-i2c
> +      - const: ti,omap2430-i2c
> +      - const: ti,omap3-i2c
> +      - const: ti,omap4-i2c
> +      - items:
> +          - enum:
> +              - ti,am4372-i2c
> +              - ti,am64-i2c
> +              - ti,am654-i2c
> +              - ti,j721e-i2c
> +          - const: ti,omap4-i2c
> +
> +  ti,hwmods:
> +    description:
> +      (DEPRECATED) Must be "i2c<n>", n being the instance number (1-based).
> +      This property is applicable only on legacy platforms mainly omap2/3
> +      and ti81xx and should not be used on other platforms.
> +    $ref: /schemas/types.yaml#/definitions/string
> +    items:
> +      - pattern: "^i2c([1-9])$"
> +
> +  dmas:
> +    minItems: 1
> +    maxItems: 2
> +
> +  dma-names:
> +    items:
> +      - const: tx
> +      - const: rx
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: fck
> +
> +  clock-frequency: true
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    main_i2c0: i2c@2000000 {
> +            compatible = "ti,j721e-i2c", "ti,omap4-i2c";
> +            reg = <0x2000000 0x100>;
> +            interrupts = <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +         };
>

On 5/7/21 12:24 PM, Grygorii Strashko wrote:
> 
> 
> On 06/05/2021 17:00, Vignesh Raghavendra wrote:
>> Convert i2c-omap.txt to YAML schema for better checks and documentation.
>>
>> Following properties were used in DT but were not documented in txt
>> bindings and has been included in YAML schema:
>> 1. Include ti,am4372-i2c compatible
>> 2. Include dmas property used in few OMAP dts files
> 
> The DMA is not supported by i2c-omap driver, so wouldn't be better to
> just drop dmas from DTBs to avoid confusions?
> It can be added later.
> 

Will do.. I will also send patches dropping dmas from dts that currently
have them populated.

Regards
Vignesh

On 07/05/2021 17:36, Andreas Kemnade wrote:
> On Fri, 7 May 2021 19:45:45 +0530
> Vignesh Raghavendra <vigneshr@ti.com> wrote:
> 
>> On 5/7/21 12:24 PM, Grygorii Strashko wrote:
>>>
>>>
>>> On 06/05/2021 17:00, Vignesh Raghavendra wrote:
>>>> Convert i2c-omap.txt to YAML schema for better checks and documentation.
>>>>
>>>> Following properties were used in DT but were not documented in txt
>>>> bindings and has been included in YAML schema:
>>>> 1. Include ti,am4372-i2c compatible
>>>> 2. Include dmas property used in few OMAP dts files
>>>
>>> The DMA is not supported by i2c-omap driver, so wouldn't be better to
>>> just drop dmas from DTBs to avoid confusions?
>>> It can be added later.
>>>    
>>
>> Will do.. I will also send patches dropping dmas from dts that currently
>> have them populated.
>>
> hmm, we have
> - DO attempt to make bindings complete even if a driver doesn't support some
>    features. For example, if a device has an interrupt, then include the
>    'interrupts' property even if the driver is only polled mode.
> 
> in Documentation/devicetree/bindings/writing-bindings.rst
> Shouln't the dma stay there if the hardware supports it? Devicetree
> should describe the hardware not the driver if I understood things
> right.

True.  But my above statement is also valid - it introduces confusion from user point of view.
More over, 'dmas' is not part of original binding and were randomly added to some SoCs.
And it's much more easy to extend binding (in the future) then remove something after.

I leave it to Vignesh, Tony to decide.

On Fri, May 07, 2021 at 08:24:59PM +0300, Grygorii Strashko wrote:
> 
> 
> On 07/05/2021 17:36, Andreas Kemnade wrote:
> > On Fri, 7 May 2021 19:45:45 +0530
> > Vignesh Raghavendra <vigneshr@ti.com> wrote:
> > 
> > > On 5/7/21 12:24 PM, Grygorii Strashko wrote:
> > > > 
> > > > 
> > > > On 06/05/2021 17:00, Vignesh Raghavendra wrote:
> > > > > Convert i2c-omap.txt to YAML schema for better checks and documentation.
> > > > > 
> > > > > Following properties were used in DT but were not documented in txt
> > > > > bindings and has been included in YAML schema:
> > > > > 1. Include ti,am4372-i2c compatible
> > > > > 2. Include dmas property used in few OMAP dts files
> > > > 
> > > > The DMA is not supported by i2c-omap driver, so wouldn't be better to
> > > > just drop dmas from DTBs to avoid confusions?
> > > > It can be added later.
> > > 
> > > Will do.. I will also send patches dropping dmas from dts that currently
> > > have them populated.
> > > 
> > hmm, we have
> > - DO attempt to make bindings complete even if a driver doesn't support some
> >    features. For example, if a device has an interrupt, then include the
> >    'interrupts' property even if the driver is only polled mode.
> > 
> > in Documentation/devicetree/bindings/writing-bindings.rst
> > Shouln't the dma stay there if the hardware supports it? Devicetree
> > should describe the hardware not the driver if I understood things
> > right.
> 
> True.  But my above statement is also valid - it introduces confusion from user point of view.

In my OS, 'robOS', the driver supports DMA.

> More over, 'dmas' is not part of original binding and were randomly added to some SoCs.
> And it's much more easy to extend binding (in the future) then remove something after.

In this case, probably given that how it would be extended is already 
known, but it depends how you extend a binding. My above statement was 
born out of incomplete MFD and system controller bindings for the most 
part.

> I leave it to Vignesh, Tony to decide.

Fine with me.

Actually, for DMA with I2C I'd like to see someone show a usecase 
and data where it's actually beneficial. 

Rob

Hi Tony,

On 5/7/21 10:54 PM, Grygorii Strashko wrote:
> 
> 
> On 07/05/2021 17:36, Andreas Kemnade wrote:
>> On Fri, 7 May 2021 19:45:45 +0530
>> Vignesh Raghavendra <vigneshr@ti.com> wrote:
>>
>>> On 5/7/21 12:24 PM, Grygorii Strashko wrote:
>>>>
>>>>
>>>> On 06/05/2021 17:00, Vignesh Raghavendra wrote:
>>>>> Convert i2c-omap.txt to YAML schema for better checks and
>>>>> documentation.
>>>>>
>>>>> Following properties were used in DT but were not documented in txt
>>>>> bindings and has been included in YAML schema:
>>>>> 1. Include ti,am4372-i2c compatible
>>>>> 2. Include dmas property used in few OMAP dts files
>>>>
>>>> The DMA is not supported by i2c-omap driver, so wouldn't be better to
>>>> just drop dmas from DTBs to avoid confusions?
>>>> It can be added later.
>>>>    
>>>
>>> Will do.. I will also send patches dropping dmas from dts that currently
>>> have them populated.
>>>
>> hmm, we have
>> - DO attempt to make bindings complete even if a driver doesn't
>> support some
>>    features. For example, if a device has an interrupt, then include the
>>    'interrupts' property even if the driver is only polled mode.
>>
>> in Documentation/devicetree/bindings/writing-bindings.rst
>> Shouln't the dma stay there if the hardware supports it? Devicetree
>> should describe the hardware not the driver if I understood things
>> right.
> 
> True.  But my above statement is also valid - it introduces confusion
> from user point of view.
> More over, 'dmas' is not part of original binding and were randomly
> added to some SoCs.
> And it's much more easy to extend binding (in the future) then remove
> something after.
> 
> I leave it to Vignesh, Tony to decide.
> 

What do you prefer here? Removing dmas from schema would mean I would
have to delete dmas property from omap2/3 dtsi files that list dmas
property today? Note that driver does not support DMA mode today.


Regards
Vignesh