diff mbox series

[1/2] dt-bindings: timer: Update TI timer to yaml

Message ID 20220411111858.16814-1-tony@atomide.com (mailing list archive)
State New, archived
Headers show
Series [1/2] dt-bindings: timer: Update TI timer to yaml | expand

Commit Message

Tony Lindgren April 11, 2022, 11:18 a.m. UTC
Let's update the TI timer binding to use yaml. As this binding is specific
to the TI dual-mode timers also known as dm-timers, let's use file name
ti,timer-dm.yaml to avoid confusion with other timers.

We also correct the issue with the old binding that was out of date for
several properties.

The am43 related timers are undocumented, but compatible with the am3
timers. Let's add the am43 timers too.

The dm814 and dm816 timers are missing, let's add them.

Some timers on some SoCs are dual mapped, like the ABE timers on omap4
and 5. The reg property maxItems must be updated to 2.

The timer clocks can be managed by the parent interconnect target module
with no clocks assigned for the timer node. And in some cases the SoC may
need to configure additional clocks for the timer in addition to the
functional clock.

The clock names are optional and not specific to the comptible property.
For example, dra7 timers on l3 interconnect do not need clock-names,while
the timers on dra7 l4 interconnect need them with both being compatible
with ti,omap5430-timer.

Cc: Daniel Lezcano <daniel.lezcano@linaro.org>
Cc: Keerthy <j-keerthy@ti.com>
Cc: Nishanth Menon <nm@ti.com>
Cc: Vignesh Raghavendra <vigneshr@ti.com>
Signed-off-by: Tony Lindgren <tony@atomide.com>
---
 .../bindings/pwm/pwm-omap-dmtimer.txt         |   2 +-
 .../bindings/timer/ti,timer-dm.yaml           | 128 ++++++++++++++++++
 .../devicetree/bindings/timer/ti,timer.txt    |  44 ------
 3 files changed, 129 insertions(+), 45 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
 delete mode 100644 Documentation/devicetree/bindings/timer/ti,timer.txt

Comments

Grygorii Strashko April 12, 2022, 8:38 a.m. UTC | #1
On 11/04/2022 14:18, Tony Lindgren wrote:
> Let's update the TI timer binding to use yaml. As this binding is specific
> to the TI dual-mode timers also known as dm-timers, let's use file name
> ti,timer-dm.yaml to avoid confusion with other timers.
> 
> We also correct the issue with the old binding that was out of date for
> several properties.
> 
> The am43 related timers are undocumented, but compatible with the am3
> timers. Let's add the am43 timers too.
> 
> The dm814 and dm816 timers are missing, let's add them.
> 
> Some timers on some SoCs are dual mapped, like the ABE timers on omap4
> and 5. The reg property maxItems must be updated to 2.
> 
> The timer clocks can be managed by the parent interconnect target module
> with no clocks assigned for the timer node. And in some cases the SoC may
> need to configure additional clocks for the timer in addition to the
> functional clock.
> 
> The clock names are optional and not specific to the comptible property.
> For example, dra7 timers on l3 interconnect do not need clock-names,while
> the timers on dra7 l4 interconnect need them with both being compatible
> with ti,omap5430-timer.
> 
> Cc: Daniel Lezcano <daniel.lezcano@linaro.org>
> Cc: Keerthy <j-keerthy@ti.com>
> Cc: Nishanth Menon <nm@ti.com>
> Cc: Vignesh Raghavendra <vigneshr@ti.com>
> Signed-off-by: Tony Lindgren <tony@atomide.com>
> ---
>   .../bindings/pwm/pwm-omap-dmtimer.txt         |   2 +-
>   .../bindings/timer/ti,timer-dm.yaml           | 128 ++++++++++++++++++
>   .../devicetree/bindings/timer/ti,timer.txt    |  44 ------
>   3 files changed, 129 insertions(+), 45 deletions(-)
>   create mode 100644 Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
>   delete mode 100644 Documentation/devicetree/bindings/timer/ti,timer.txt
> 
> diff --git a/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
> --- a/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
> +++ b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
> @@ -2,7 +2,7 @@
>   
>   Required properties:
>   - compatible: Shall contain "ti,omap-dmtimer-pwm".
> -- ti,timers: phandle to PWM capable OMAP timer. See timer/ti,timer.txt for info
> +- ti,timers: phandle to PWM capable OMAP timer. See timer/ti,timer-dm.yaml for info
>     about these timers.
>   - #pwm-cells: Should be 3. See pwm.yaml in this directory for a description of
>     the cells format.
> diff --git a/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml b/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
> new file mode 100644
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
> @@ -0,0 +1,128 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/timer/ti,timer-dm.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: TI dual-mode timer
> +
> +maintainers:
> +  - Tony Lindgren <tony@atomide.com>
> +
> +description: |
> +  The TI dual-mode timer is a general purpose timer with PWM capabilities.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - ti,am335x-timer
> +              - ti,am335x-timer-1ms
> +              - ti,dm814-timer
> +              - ti,dm816-timer
> +              - ti,omap2420-timer
> +              - ti,omap3430-timer
> +              - ti,omap4430-timer
> +              - ti,omap5430-timer
> +      - items:
> +          - const: ti,am4372-timer
> +          - const: ti,am335x-timer
> +      - items:
> +          - const: ti,am4372-timer-1ms
> +          - const: ti,am335x-timer-1ms
> +
> +  reg:
> +    minItems: 1
> +    maxItems: 2
> +    description: Timer IO register range

if i'm not mistaken - you need to provide description for every item unless it's obviously determined by "-names" properties

> +
> +  clocks:
> +    description:
> +      The functional clock for the timer. Some SoCs like omap24xx also have a
> +      separate interface clock, and some clocks may be only defined for the
> +      interconnect target module parent.

ditto


> +    minItems: 1
> +    maxItems: 2
> +
> +  clock-names:
> +    description:
> +      Timer clock names like "fck", "timer_sys_ck".

and description here make no sense

> +    oneOf:
> +      - enum: [ ick, fck ]
> +      - items:
> +          - const: fck
> +          - enum: [ ick, timer_sys_ck ]
> +
> +  interrupts:
> +    description:
> +      Interrupt if available. The timer PWM features may be usable
> +      in a limited way even without interrupts.
> +    maxItems: 1
> +
> +  ti,timer-alwon:
> +    description:
> +      Timer is always enabled when the SoC is powered. Note that some SoCs like
> +      am335x can suspend to PM coprocessor RTC only mode and in that case the
> +      SoC power is cut including timers.
> +    type: boolean
> +
> +  ti,timer-dsp:
> +    description:
> +      Timer is routable to the DSP in addition to the operating system.
> +    type: boolean
> +
> +  ti,timer-pwm:
> +    description:
> +      Timer has been wired for PWM capability.
> +    type: boolean
> +
> +  ti,timer-secure:
> +    description:
> +      Timer access has been limited to secure mode only.
> +    type: boolean
> +
> +  ti,hwmods:
> +    description:
> +      Name of the HWMOD associated with timer. This is for legacy
> +      omap2/3 platforms only.
> +    $ref: /schemas/types.yaml#/definitions/string
> +    deprecated: true
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +additionalProperties: false
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - ti,dm814-timer
> +              - ti,dm816-timer
> +              - ti,omap2420-timer
> +              - ti,omap3430-timer
> +    then:
> +      properties:
> +        ti,hwmods:
> +          items:
> +            - pattern: "^timer([1-9]|1[0-2])$"
> +    else:
> +      properties:
> +        ti,hwmods: false
> +
> +examples:
> +  - |
> +    timer1: timer@0 {
> +      compatible = "ti,am335x-timer-1ms";
> +      reg = <0x0 0x400>;
> +      interrupts = <67>;
> +      ti,timer-alwon;
> +      clocks = <&timer1_fck>;
> +      clock-names = "fck";
> +    };
> +...
> diff --git a/Documentation/devicetree/bindings/timer/ti,timer.txt b/Documentation/devicetree/bindings/timer/ti,timer.txt
> deleted file mode 100644
> --- a/Documentation/devicetree/bindings/timer/ti,timer.txt
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -OMAP Timer bindings
> -
> -Required properties:
> -- compatible:		Should be set to one of the below. Please note that
> -			OMAP44xx devices have timer instances that are 100%
> -			register compatible with OMAP3xxx devices as well as
> -			newer timers that are not 100% register compatible.
> -			So for OMAP44xx devices timer instances may use
> -			different compatible strings.
> -
> -			ti,omap2420-timer (applicable to OMAP24xx devices)
> -			ti,omap3430-timer (applicable to OMAP3xxx/44xx devices)
> -			ti,omap4430-timer (applicable to OMAP44xx devices)
> -			ti,omap5430-timer (applicable to OMAP543x devices)
> -			ti,am335x-timer	(applicable to AM335x devices)
> -			ti,am335x-timer-1ms (applicable to AM335x devices)
> -
> -- reg:			Contains timer register address range (base address and
> -			length).
> -- interrupts: 		Contains the interrupt information for the timer. The
> -			format is being dependent on which interrupt controller
> -			the OMAP device uses.
> -- ti,hwmods:		Name of the hwmod associated to the timer, "timer<X>",
> -			where <X> is the instance number of the timer from the
> -			HW spec.
> -
> -Optional properties:
> -- ti,timer-alwon:	Indicates the timer is in an alway-on power domain.
> -- ti,timer-dsp:		Indicates the timer can interrupt the on-chip DSP in
> -			addition to the ARM CPU.
> -- ti,timer-pwm: 	Indicates the timer can generate a PWM output.
> -- ti,timer-secure: 	Indicates the timer is reserved on a secure OMAP device
> -			and therefore cannot be used by the kernel.
> -
> -Example:
> -
> -timer12: timer@48304000 {
> -	compatible = "ti,omap3430-timer";
> -	reg = <0x48304000 0x400>;
> -	interrupts = <95>;
> -	ti,hwmods = "timer12"
> -	ti,timer-alwon;
> -	ti,timer-secure;
> -};
Tony Lindgren April 12, 2022, 8:51 a.m. UTC | #2
* Grygorii Strashko <grygorii.strashko@ti.com> [220412 08:35]:
> On 11/04/2022 14:18, Tony Lindgren wrote:
> > +  reg:
> > +    minItems: 1
> > +    maxItems: 2
> > +    description: Timer IO register range
> 
> if i'm not mistaken - you need to provide description for every item unless it's obviously determined by "-names" properties

OK thanks will update for reg and clocks.

> > +  clock-names:
> > +    description:
> > +      Timer clock names like "fck", "timer_sys_ck".
> 
> and description here make no sense

So you just want to leave out the description from the clock-names if
I read your comment above right?

Regards,

Tony
Krzysztof Kozlowski April 12, 2022, 9 a.m. UTC | #3
On 11/04/2022 13:18, Tony Lindgren wrote:
> Let's update the TI timer binding to use yaml. As this binding is specific
> to the TI dual-mode timers also known as dm-timers, let's use file name
> ti,timer-dm.yaml to avoid confusion with other timers.
> 
> We also correct the issue with the old binding that was out of date for
> several properties.
> 
> The am43 related timers are undocumented, but compatible with the am3
> timers. Let's add the am43 timers too.
> 
> The dm814 and dm816 timers are missing, let's add them.
> 
> Some timers on some SoCs are dual mapped, like the ABE timers on omap4
> and 5. The reg property maxItems must be updated to 2.

(...)

> +  reg:
> +    minItems: 1
> +    maxItems: 2
> +    description: Timer IO register range
> +

Apart from what Grygorii said, it would be useful if you add "if:then:"
case constraining it per implementation (as I understood from commit msg
only some use double mapping).

This looks like:
https://elixir.bootlin.com/linux/v5.18-rc2/source/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml#L53

Similarly should be done for clocks, unless it's impossible (same
compatible uses different setups of clocks).

BTW, it's a bit confusing it is not a v2...


Best regards,
Krzysztof
Tony Lindgren April 12, 2022, 9:10 a.m. UTC | #4
Hi,

* Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> [220412 08:58]:
> On 11/04/2022 13:18, Tony Lindgren wrote:
> > Some timers on some SoCs are dual mapped, like the ABE timers on omap4
> > and 5. The reg property maxItems must be updated to 2.

So on omap4/5 there are timers with a single IO register and with
dual mapped IO registers.

> (...)
> 
> > +  reg:
> > +    minItems: 1
> > +    maxItems: 2
> > +    description: Timer IO register range
> > +
> 
> Apart from what Grygorii said, it would be useful if you add "if:then:"
> case constraining it per implementation (as I understood from commit msg
> only some use double mapping).
> 
> This looks like:
> https://elixir.bootlin.com/linux/v5.18-rc2/source/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml#L53

Yes I tried, but see the above. The compatible property is the same for
single mapped and dual mapped timers on the same SoC for omap4/5.

> Similarly should be done for clocks, unless it's impossible (same
> compatible uses different setups of clocks).

It's the same situation for clocks, the same compatible is used for
timers with one clock and timers with two clocks for example on dra7.

I'll check the description again to clarify this, maybe it's not
clear yet.

> BTW, it's a bit confusing it is not a v2...

Oops sorry looks like I forgot to update the version.

Regards,

Tony
Krzysztof Kozlowski April 12, 2022, 9:13 a.m. UTC | #5
On 12/04/2022 11:10, Tony Lindgren wrote:
>> Apart from what Grygorii said, it would be useful if you add "if:then:"
>> case constraining it per implementation (as I understood from commit msg
>> only some use double mapping).
>>
>> This looks like:
>> https://elixir.bootlin.com/linux/v5.18-rc2/source/Documentation/devicetree/bindings/clock/samsung,exynos7885-clock.yaml#L53
> 
> Yes I tried, but see the above. The compatible property is the same for
> single mapped and dual mapped timers on the same SoC for omap4/5.

But all on others this is single mapped? Then at least reduce them to
one item inside allOf:if:then. The omap4/5 will accept both - one and
two items.

Best regards,
Krzysztof
Grygorii Strashko April 12, 2022, 9:48 a.m. UTC | #6
On 12/04/2022 11:51, Tony Lindgren wrote:
> * Grygorii Strashko <grygorii.strashko@ti.com> [220412 08:35]:
>> On 11/04/2022 14:18, Tony Lindgren wrote:
>>> +  reg:
>>> +    minItems: 1
>>> +    maxItems: 2
>>> +    description: Timer IO register range
>>
>> if i'm not mistaken - you need to provide description for every item unless it's obviously determined by "-names" properties
> 
> OK thanks will update for reg and clocks.
> 
>>> +  clock-names:
>>> +    description:
>>> +      Timer clock names like "fck", "timer_sys_ck".
>>
>> and description here make no sense
> 
> So you just want to leave out the description from the clock-names if
> I read your comment above right?

yes.

> 
> Regards,
> 
> Tony
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
--- a/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
+++ b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt
@@ -2,7 +2,7 @@ 
 
 Required properties:
 - compatible: Shall contain "ti,omap-dmtimer-pwm".
-- ti,timers: phandle to PWM capable OMAP timer. See timer/ti,timer.txt for info
+- ti,timers: phandle to PWM capable OMAP timer. See timer/ti,timer-dm.yaml for info
   about these timers.
 - #pwm-cells: Should be 3. See pwm.yaml in this directory for a description of
   the cells format.
diff --git a/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml b/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
new file mode 100644
--- /dev/null
+++ b/Documentation/devicetree/bindings/timer/ti,timer-dm.yaml
@@ -0,0 +1,128 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/timer/ti,timer-dm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI dual-mode timer
+
+maintainers:
+  - Tony Lindgren <tony@atomide.com>
+
+description: |
+  The TI dual-mode timer is a general purpose timer with PWM capabilities.
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - ti,am335x-timer
+              - ti,am335x-timer-1ms
+              - ti,dm814-timer
+              - ti,dm816-timer
+              - ti,omap2420-timer
+              - ti,omap3430-timer
+              - ti,omap4430-timer
+              - ti,omap5430-timer
+      - items:
+          - const: ti,am4372-timer
+          - const: ti,am335x-timer
+      - items:
+          - const: ti,am4372-timer-1ms
+          - const: ti,am335x-timer-1ms
+
+  reg:
+    minItems: 1
+    maxItems: 2
+    description: Timer IO register range
+
+  clocks:
+    description:
+      The functional clock for the timer. Some SoCs like omap24xx also have a
+      separate interface clock, and some clocks may be only defined for the
+      interconnect target module parent.
+    minItems: 1
+    maxItems: 2
+
+  clock-names:
+    description:
+      Timer clock names like "fck", "timer_sys_ck".
+    oneOf:
+      - enum: [ ick, fck ]
+      - items:
+          - const: fck
+          - enum: [ ick, timer_sys_ck ]
+
+  interrupts:
+    description:
+      Interrupt if available. The timer PWM features may be usable
+      in a limited way even without interrupts.
+    maxItems: 1
+
+  ti,timer-alwon:
+    description:
+      Timer is always enabled when the SoC is powered. Note that some SoCs like
+      am335x can suspend to PM coprocessor RTC only mode and in that case the
+      SoC power is cut including timers.
+    type: boolean
+
+  ti,timer-dsp:
+    description:
+      Timer is routable to the DSP in addition to the operating system.
+    type: boolean
+
+  ti,timer-pwm:
+    description:
+      Timer has been wired for PWM capability.
+    type: boolean
+
+  ti,timer-secure:
+    description:
+      Timer access has been limited to secure mode only.
+    type: boolean
+
+  ti,hwmods:
+    description:
+      Name of the HWMOD associated with timer. This is for legacy
+      omap2/3 platforms only.
+    $ref: /schemas/types.yaml#/definitions/string
+    deprecated: true
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+additionalProperties: false
+
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - ti,dm814-timer
+              - ti,dm816-timer
+              - ti,omap2420-timer
+              - ti,omap3430-timer
+    then:
+      properties:
+        ti,hwmods:
+          items:
+            - pattern: "^timer([1-9]|1[0-2])$"
+    else:
+      properties:
+        ti,hwmods: false
+
+examples:
+  - |
+    timer1: timer@0 {
+      compatible = "ti,am335x-timer-1ms";
+      reg = <0x0 0x400>;
+      interrupts = <67>;
+      ti,timer-alwon;
+      clocks = <&timer1_fck>;
+      clock-names = "fck";
+    };
+...
diff --git a/Documentation/devicetree/bindings/timer/ti,timer.txt b/Documentation/devicetree/bindings/timer/ti,timer.txt
deleted file mode 100644
--- a/Documentation/devicetree/bindings/timer/ti,timer.txt
+++ /dev/null
@@ -1,44 +0,0 @@ 
-OMAP Timer bindings
-
-Required properties:
-- compatible:		Should be set to one of the below. Please note that
-			OMAP44xx devices have timer instances that are 100%
-			register compatible with OMAP3xxx devices as well as
-			newer timers that are not 100% register compatible.
-			So for OMAP44xx devices timer instances may use
-			different compatible strings.
-
-			ti,omap2420-timer (applicable to OMAP24xx devices)
-			ti,omap3430-timer (applicable to OMAP3xxx/44xx devices)
-			ti,omap4430-timer (applicable to OMAP44xx devices)
-			ti,omap5430-timer (applicable to OMAP543x devices)
-			ti,am335x-timer	(applicable to AM335x devices)
-			ti,am335x-timer-1ms (applicable to AM335x devices)
-
-- reg:			Contains timer register address range (base address and
-			length).
-- interrupts: 		Contains the interrupt information for the timer. The
-			format is being dependent on which interrupt controller
-			the OMAP device uses.
-- ti,hwmods:		Name of the hwmod associated to the timer, "timer<X>",
-			where <X> is the instance number of the timer from the
-			HW spec.
-
-Optional properties:
-- ti,timer-alwon:	Indicates the timer is in an alway-on power domain.
-- ti,timer-dsp:		Indicates the timer can interrupt the on-chip DSP in
-			addition to the ARM CPU.
-- ti,timer-pwm: 	Indicates the timer can generate a PWM output.
-- ti,timer-secure: 	Indicates the timer is reserved on a secure OMAP device
-			and therefore cannot be used by the kernel.
-
-Example:
-
-timer12: timer@48304000 {
-	compatible = "ti,omap3430-timer";
-	reg = <0x48304000 0x400>;
-	interrupts = <95>;
-	ti,hwmods = "timer12"
-	ti,timer-alwon;
-	ti,timer-secure;
-};