[RFC][PATCHv5 4/4] Documentation: Add device tree bindings for Freescale FTM PWM.

[Xiubo Li-B47053]

> > This adds the Document for Freescale FTM PWM driver under
> > Documentation/devicetree/bindings/pwm/.
> >
> > Signed-off-by: Xiubo Li <Li.Xiubo at freescale.com>
> > ---
> > .../devicetree/bindings/pwm/pwm-fsl-ftm.txt        | 34
> ++++++++++++++++++++++
> > 1 file changed, 34 insertions(+)
> > create mode 100644
> > Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt
> >
> > diff --git a/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt
> > b/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt
> > new file mode 100644
> > index 0000000..175b762
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/pwm/pwm-fsl-ftm.txt
> > @@ -0,0 +1,34 @@
> > +Freescale FTM PWM controller
> 
> What does FTM stand for, and can we spell out PWM at least once early on.
> 

"FTM" is for short of "FlexTimer Module", I'll use the full name then.

> > +
> > +Required properties:
> > +- compatible: Should be "fsl,vf610-ftm-pwm"
> > +- reg: Physical base address and length of the controller's registers
> > +- #pwm-cells: Should be 3. See pwm.txt in this directory for a
> > +description of
> > +  the cells format.
> > +- clock-names : Includes the following module clock source entries:
> > +    "ftm0" (system clock),
> > +    "ftm0_fix_sel" (fixed frequency clock),
> > +    "ftm0_ext_sel" (external clock)
> > +- clocks : Must contain a clock specifier for each entry in
> > +clock-names,
> > +  See ../clock/clock-bindings.txt for details of the property values.
> > +- fsl,pwm-counter-clk: The FTM PWM counter clock source, should be
> > +one of the
> > +  entries in clock-names.
> 
> Why do we need this, why not just have only the clock-names/clocks
> reference the clk that is actually used?
> 

As I have replied before, the FTM has two clock sources: the module clock and the counter clock.

The counter clock source is selectable depends on different board and also the hardware design:
+++++
* FTM source clock is selectable
* Source clock can be the system clock, the fixed frequency clock, or an external
clock
* Fixed frequency clock is an additional clock input to allow the selection of an on
chip clock source other than the system clock
* Selecting external clock connects FTM clock to a chip level input pin therefore
allowing to synchronize the FTM counter with an off chip clock source
-----
>From the above description we can see that the external clock source can allow to synchronize the
FTM counter with an off chip clock source.

As the chip spec permits the counter clock source be selectable, so the different board maybe has different
implementation, if the driver do not support, this will be a bug.


> > +- pinctrl-names: must contain a "default" entry.
> > +- pinctrl-NNN: One property must exist for each entry in pinctrl-names.
> > +  See ../pinctrl/pinctrl-bindings.txt for details of the property
> values.
> 
> let's drop the .. when making directory references.
> 

Is absolute path " Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt " or just "pinctrl/pinctrl-bindings.txt " ?


--
Xiubo