| Message ID | 20190521145141.9813-4-paul@crapouillou.net (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v12,01/13] dt-bindings: ingenic: Add DT bindings for TCU clocks | expand |
On Tue, May 21, 2019 at 04:51:31PM +0200, Paul Cercueil wrote: > Add documentation about how to properly use the Ingenic TCU > (Timer/Counter Unit) drivers from devicetree. > > Signed-off-by: Paul Cercueil <paul@crapouillou.net> > --- > > Notes: > v4: New patch in this series. Corresponds to V2 patches 3-4-5 with > added content. > > v5: - Edited PWM/watchdog DT bindings documentation to point to the new > document. > - Moved main document to > Documentation/devicetree/bindings/timer/ingenic,tcu.txt > - Updated documentation to reflect the new devicetree bindings. > > v6: - Removed PWM/watchdog documentation files as asked by upstream > - Removed doc about properties that should be implicit > - Removed doc about ingenic,timer-channel / > ingenic,clocksource-channel as they are gone > - Fix WDT clock name in the binding doc > - Fix lengths of register areas in watchdog/pwm nodes > > v7: No change > > v8: - Fix address of the PWM node > - Added doc about system timer and clocksource children nodes > > v9: - Remove doc about system timer and clocksource children > nodes... > - Add doc about ingenic,pwm-channels-mask property > > v10: No change > > v11: Fix info about default value of ingenic,pwm-channels-mask > > v12: Drop sub-nodes for now; they will be introduced in a follow-up > patchset. Why? I believe I acked them. > > .../devicetree/bindings/timer/ingenic,tcu.txt | 59 +++++++++++++++++++ > 1 file changed, 59 insertions(+) > create mode 100644 Documentation/devicetree/bindings/timer/ingenic,tcu.txt > > diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt > new file mode 100644 > index 000000000000..d101cd72c9b0 > --- /dev/null > +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt > @@ -0,0 +1,59 @@ > +Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings > +========================================================== > + > +For a description of the TCU hardware and drivers, have a look at > +Documentation/mips/ingenic-tcu.txt. > + > +Required properties: > + > +- compatible: Must be one of: > + * "ingenic,jz4740-tcu" > + * "ingenic,jz4725b-tcu" > + * "ingenic,jz4770-tcu" > +- reg: Should be the offset/length value corresponding to the TCU registers > +- clocks: List of phandle & clock specifiers for clocks external to the TCU. > + The "pclk", "rtc" and "ext" clocks should be provided. The "tcu" clock > + should be provided if the SoC has it. > +- clock-names: List of name strings for the external clocks. > +- #clock-cells: Should be <1>; > + Clock consumers specify this argument to identify a clock. The valid values > + may be found in <dt-bindings/clock/ingenic,tcu.h>. > +- interrupt-controller : Identifies the node as an interrupt controller > +- #interrupt-cells : Specifies the number of cells needed to encode an > + interrupt source. The value should be 1. > +- interrupt-parent : phandle of the interrupt controller. Drop this 'interrupt-parent' is implied and could be in a parent node. > +- interrupts : Specifies the interrupt the controller is connected to. > + > +Optional properties: > + > +- ingenic,pwm-channels-mask: Bitmask of TCU channels reserved for PWM use. > + Default value is 0xfc. > + > + > +Example > +========================================================== > + > +#include <dt-bindings/clock/jz4770-cgu.h> > + > +/ { > + tcu: timer@10002000 { > + compatible = "ingenic,jz4770-tcu"; > + reg = <0x10002000 0x1000>; > + #address-cells = <1>; > + #size-cells = <1>; > + ranges = <0x0 0x10002000 0x1000>; > + > + #clock-cells = <1>; > + > + clocks = <&cgu JZ4770_CLK_RTC > + &cgu JZ4770_CLK_EXT > + &cgu JZ4770_CLK_PCLK>; > + clock-names = "rtc", "ext", "pclk"; > + > + interrupt-controller; > + #interrupt-cells = <1>; > + > + interrupt-parent = <&intc>; > + interrupts = <27 26 25>; > + }; > +}; > -- > 2.21.0.593.g511ec345e18 >
Le ven. 24 mai 2019 à 22:21, Rob Herring <robh@kernel.org> a écrit : > On Tue, May 21, 2019 at 04:51:31PM +0200, Paul Cercueil wrote: >> Add documentation about how to properly use the Ingenic TCU >> (Timer/Counter Unit) drivers from devicetree. >> >> Signed-off-by: Paul Cercueil <paul@crapouillou.net> >> --- >> >> Notes: >> v4: New patch in this series. Corresponds to V2 patches 3-4-5 >> with >> added content. >> >> v5: - Edited PWM/watchdog DT bindings documentation to point to >> the new >> document. >> - Moved main document to >> Documentation/devicetree/bindings/timer/ingenic,tcu.txt >> - Updated documentation to reflect the new devicetree bindings. >> >> v6: - Removed PWM/watchdog documentation files as asked by >> upstream >> - Removed doc about properties that should be implicit >> - Removed doc about ingenic,timer-channel / >> ingenic,clocksource-channel as they are gone >> - Fix WDT clock name in the binding doc >> - Fix lengths of register areas in watchdog/pwm nodes >> >> v7: No change >> >> v8: - Fix address of the PWM node >> - Added doc about system timer and clocksource children nodes >> >> v9: - Remove doc about system timer and clocksource children >> nodes... >> - Add doc about ingenic,pwm-channels-mask property >> >> v10: No change >> >> v11: Fix info about default value of ingenic,pwm-channels-mask >> >> v12: Drop sub-nodes for now; they will be introduced in a >> follow-up >> patchset. > > Why? I believe I acked them. The patchset was too big, and I've already been trying to get it upstream for more than one year now. So I cut it in half in hope that it'll be easier to upstream it that way. >> >> .../devicetree/bindings/timer/ingenic,tcu.txt | 59 >> +++++++++++++++++++ >> 1 file changed, 59 insertions(+) >> create mode 100644 >> Documentation/devicetree/bindings/timer/ingenic,tcu.txt >> >> diff --git >> a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt >> b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt >> new file mode 100644 >> index 000000000000..d101cd72c9b0 >> --- /dev/null >> +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt >> @@ -0,0 +1,59 @@ >> +Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings >> +========================================================== >> + >> +For a description of the TCU hardware and drivers, have a look at >> +Documentation/mips/ingenic-tcu.txt. >> + >> +Required properties: >> + >> +- compatible: Must be one of: >> + * "ingenic,jz4740-tcu" >> + * "ingenic,jz4725b-tcu" >> + * "ingenic,jz4770-tcu" >> +- reg: Should be the offset/length value corresponding to the TCU >> registers >> +- clocks: List of phandle & clock specifiers for clocks external >> to the TCU. >> + The "pclk", "rtc" and "ext" clocks should be provided. The "tcu" >> clock >> + should be provided if the SoC has it. >> +- clock-names: List of name strings for the external clocks. >> +- #clock-cells: Should be <1>; >> + Clock consumers specify this argument to identify a clock. The >> valid values >> + may be found in <dt-bindings/clock/ingenic,tcu.h>. >> +- interrupt-controller : Identifies the node as an interrupt >> controller >> +- #interrupt-cells : Specifies the number of cells needed to >> encode an >> + interrupt source. The value should be 1. >> +- interrupt-parent : phandle of the interrupt controller. > > Drop this 'interrupt-parent' is implied and could be in a parent node. > >> +- interrupts : Specifies the interrupt the controller is connected >> to. >> + >> +Optional properties: >> + >> +- ingenic,pwm-channels-mask: Bitmask of TCU channels reserved for >> PWM use. >> + Default value is 0xfc. >> + >> + >> +Example >> +========================================================== >> + >> +#include <dt-bindings/clock/jz4770-cgu.h> >> + >> +/ { >> + tcu: timer@10002000 { >> + compatible = "ingenic,jz4770-tcu"; >> + reg = <0x10002000 0x1000>; >> + #address-cells = <1>; >> + #size-cells = <1>; >> + ranges = <0x0 0x10002000 0x1000>; >> + >> + #clock-cells = <1>; >> + >> + clocks = <&cgu JZ4770_CLK_RTC >> + &cgu JZ4770_CLK_EXT >> + &cgu JZ4770_CLK_PCLK>; >> + clock-names = "rtc", "ext", "pclk"; >> + >> + interrupt-controller; >> + #interrupt-cells = <1>; >> + >> + interrupt-parent = <&intc>; >> + interrupts = <27 26 25>; >> + }; >> +}; >> -- >> 2.21.0.593.g511ec345e18 >>
On Sat, May 25, 2019 at 1:13 PM Paul Cercueil <paul@crapouillou.net> wrote: > > > > Le ven. 24 mai 2019 à 22:21, Rob Herring <robh@kernel.org> a écrit : > > On Tue, May 21, 2019 at 04:51:31PM +0200, Paul Cercueil wrote: > >> Add documentation about how to properly use the Ingenic TCU > >> (Timer/Counter Unit) drivers from devicetree. > >> > >> Signed-off-by: Paul Cercueil <paul@crapouillou.net> > >> --- > >> > >> Notes: > >> v4: New patch in this series. Corresponds to V2 patches 3-4-5 > >> with > >> added content. > >> > >> v5: - Edited PWM/watchdog DT bindings documentation to point to > >> the new > >> document. > >> - Moved main document to > >> Documentation/devicetree/bindings/timer/ingenic,tcu.txt > >> - Updated documentation to reflect the new devicetree bindings. > >> > >> v6: - Removed PWM/watchdog documentation files as asked by > >> upstream > >> - Removed doc about properties that should be implicit > >> - Removed doc about ingenic,timer-channel / > >> ingenic,clocksource-channel as they are gone > >> - Fix WDT clock name in the binding doc > >> - Fix lengths of register areas in watchdog/pwm nodes > >> > >> v7: No change > >> > >> v8: - Fix address of the PWM node > >> - Added doc about system timer and clocksource children nodes > >> > >> v9: - Remove doc about system timer and clocksource children > >> nodes... > >> - Add doc about ingenic,pwm-channels-mask property > >> > >> v10: No change > >> > >> v11: Fix info about default value of ingenic,pwm-channels-mask > >> > >> v12: Drop sub-nodes for now; they will be introduced in a > >> follow-up > >> patchset. > > > > Why? I believe I acked them. > > The patchset was too big, and I've already been trying to get it > upstream for > more than one year now. So I cut it in half in hope that it'll be > easier to > upstream it that way. You can drop the driver part and keep the binding. Unlike drivers, we don't want bindings to needlessly evolve, and you don't have to wait til a driver implements some functionality to add that to the binding. Rob
diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt new file mode 100644 index 000000000000..d101cd72c9b0 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt @@ -0,0 +1,59 @@ +Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings +========================================================== + +For a description of the TCU hardware and drivers, have a look at +Documentation/mips/ingenic-tcu.txt. + +Required properties: + +- compatible: Must be one of: + * "ingenic,jz4740-tcu" + * "ingenic,jz4725b-tcu" + * "ingenic,jz4770-tcu" +- reg: Should be the offset/length value corresponding to the TCU registers +- clocks: List of phandle & clock specifiers for clocks external to the TCU. + The "pclk", "rtc" and "ext" clocks should be provided. The "tcu" clock + should be provided if the SoC has it. +- clock-names: List of name strings for the external clocks. +- #clock-cells: Should be <1>; + Clock consumers specify this argument to identify a clock. The valid values + may be found in <dt-bindings/clock/ingenic,tcu.h>. +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value should be 1. +- interrupt-parent : phandle of the interrupt controller. +- interrupts : Specifies the interrupt the controller is connected to. + +Optional properties: + +- ingenic,pwm-channels-mask: Bitmask of TCU channels reserved for PWM use. + Default value is 0xfc. + + +Example +========================================================== + +#include <dt-bindings/clock/jz4770-cgu.h> + +/ { + tcu: timer@10002000 { + compatible = "ingenic,jz4770-tcu"; + reg = <0x10002000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x10002000 0x1000>; + + #clock-cells = <1>; + + clocks = <&cgu JZ4770_CLK_RTC + &cgu JZ4770_CLK_EXT + &cgu JZ4770_CLK_PCLK>; + clock-names = "rtc", "ext", "pclk"; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&intc>; + interrupts = <27 26 25>; + }; +};
Add documentation about how to properly use the Ingenic TCU (Timer/Counter Unit) drivers from devicetree. Signed-off-by: Paul Cercueil <paul@crapouillou.net> --- Notes: v4: New patch in this series. Corresponds to V2 patches 3-4-5 with added content. v5: - Edited PWM/watchdog DT bindings documentation to point to the new document. - Moved main document to Documentation/devicetree/bindings/timer/ingenic,tcu.txt - Updated documentation to reflect the new devicetree bindings. v6: - Removed PWM/watchdog documentation files as asked by upstream - Removed doc about properties that should be implicit - Removed doc about ingenic,timer-channel / ingenic,clocksource-channel as they are gone - Fix WDT clock name in the binding doc - Fix lengths of register areas in watchdog/pwm nodes v7: No change v8: - Fix address of the PWM node - Added doc about system timer and clocksource children nodes v9: - Remove doc about system timer and clocksource children nodes... - Add doc about ingenic,pwm-channels-mask property v10: No change v11: Fix info about default value of ingenic,pwm-channels-mask v12: Drop sub-nodes for now; they will be introduced in a follow-up patchset. .../devicetree/bindings/timer/ingenic,tcu.txt | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 Documentation/devicetree/bindings/timer/ingenic,tcu.txt