[PATCH v3 17/19] clk: at91: add PMC clk device tree binding doc.

[nicolas.ferre@atmel.com (Nicolas Ferre)]

On 08/10/2013 14:37, boris brezillon :
> On 08/10/2013 11:44, Nicolas Ferre wrote:
>> On 08/08/2013 09:19, Boris BREZILLON :
>>> This patch adds new at91 clks dt bindings documentation.
>>>
>>> Signed-off-by: Boris BREZILLON <b.brezillon@overkiz.com>
>>> ---
>>>    .../devicetree/bindings/clock/at91-clock.txt       |  312
>>> ++++++++++++++++++++
>>>    1 file changed, 312 insertions(+)
>>>    create mode 100644
>>> Documentation/devicetree/bindings/clock/at91-clock.txt
>>>
>>> diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt
>>> b/Documentation/devicetree/bindings/clock/at91-clock.txt
>>> new file mode 100644
>>> index 0000000..04739da
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt
>>> @@ -0,0 +1,312 @@
>>> +Device Tree Clock bindings for arch-at91
>>> +
>>> +This binding uses the common clock binding[1].
>>> +
>>> +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
>>> +
>>> +Required properties:
>>> +- compatible : shall be one of the following:
>>> +    "atmel,at91rm9200-pmc" or
>>> +    "atmel,at91sam9g45-pmc" or
>>> +    "atmel,at91sam9n12-pmc" or
>>> +    "atmel,at91sam9x5-pmc" or
>>> +    "atmel,at91sam9g35-pmc" or
>>
>> Already said in previous patches: 9g35 is not different from the 9x5:
>> it was a bug in the older datasheet.
> I'll drop it.
>>
>>> +    "atmel,sama5d3-pmc":
>>> +        at91 PMC (Power Management Controller)
>>> +        All at91 specific clocks (clocks defined below) must be child
>>> +        node of the PMC node.
>>> +
>>> +    "atmel,at91rm9200-clk-main":
>>> +        at91 main oscillator
>>> +
>>> +    "atmel,at91rm9200-clk-master" or
>>> +    "atmel,at91sam9x5-clk-master":
>>> +        at91 master clock
>>> +
>>> +    "atmel,at91sam9x5-clk-peripheral" or
>>> +    "atmel,at91rm9200-clk-peripheral":
>>> +        at91 peripheral clocks
>>> +
>>> +    "atmel,at91rm9200-clk-pll" or
>>> +    "atmel,at91sam9g45-clk-pll" or
>>> +    "atmel,at91sam9g20-clk-pllb" or
>>> +    "atmel,sama5d3-clk-pll":
>>> +        at91 pll clocks
>>> +
>>> +    "atmel,at91sam9x5-clk-plldiv":
>>> +        at91 plla divisor
>>> +
>>> +    "atmel,at91rm9200-clk-programmable" or
>>> +    "atmel,at91sam9g45-clk-programmable" or
>>> +    "atmel,at91sam9x5-clk-programmable":
>>> +        at91 programmable clocks
>>> +
>>> +    "atmel,at91sam9x5-clk-smd":
>>> +        at91 SMD (Soft Modem) clock
>>> +
>>> +    "atmel,at91rm9200-clk-system":
>>> +        at91 system clocks
>>> +
>>> +    "atmel,at91rm9200-clk-usb" or
>>> +    "atmel,at91sam9x5-clk-usb":
>>> +        at91 usb clock
>>> +
>>> +    "atmel,at91sam9x5-clk-utmi":
>>> +        at91 utmi clock
>>> +
>>> +Required properties for PMC node:
>>> +- reg : defines the IO memory reserved for the PMC.
>>> +- interrupts : shall be set to PMC interrupt line.
>>> +- interrupt-controller : tell that the PMC is an interrupt controller
>>> +- #interrupt-cells : must be set to 2. The first cell encodes the
>>> interrupt id
>>
>> Please add more information about these values.
>>
> The first cell encodes the clk/interrupt id, which is represented by the
> bit position in the PMC_SR register:
>    - MAIN clk = 0
>    - PLLA = 1
>    - ...
>>
>>> +             the second cell encodes the interrupt type.
>>
>> Here also: is it always the same type that shall be given? Following
>> which rule? What are the allowed values?
>
> Yes it's always IRQ_TYPE_LEVEL_HIGH, maybe I should just define one cell
> and drop the irq type cell.

Yes. I am in favor for what you propose.

>>
>>
>>> +For example:
>>> +     pmc: pmc at fffffc00 {
>>> +        compatible = "atmel,sama5d3-pmc";
>>> +        interrupts = <AT91_ID_SYS IRQ_TYPE_LEVEL_HIGH 7>;
>>
>> It is an habit not to use macro names in device tree examples (even if
>> it is true that it is more readable).
>
> I'll use numerical values instead of macros (anyway, the AT91_ID_XX will
> be dropped).
>
>>
>>> +        interrupt-controller;
>>> +        #interrupt-cells = <2>;
>>> +
>>> +        /* put at91 clocks here */
>>> +    };
>>> +
>>> +Required properties for main clock:
>>> +- interrupt-parent : must reference the PMC node.
>>> +- interrupts : shall be set to "<AT91_PMC_MOSCS IRQ_TYPE_LEVEL_HIGH>".
>>
>> Ditto. Here you can use the numerical value and also specify the macro
>> name. But the numerical value should prevail.
> Okay
>
>>
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks (optional if clock-frequency is provided) : shall be the
>>> slow clock
>>> +    phandle. This clock is used to compute the main clock rate if
>>> +    "clock-frequency" is not provided.
>>> +- clock-frequency: the main oscillator frequency.Prefer the use of
>>
>> Nit. one white space missing
>>
>>> +    "clock-frequency" over automatic clock rate computation.
>>
>>
>>> +
>>> +For example:
>>> +    main: mainck {
>>> +        compatible = "atmel,at91rm9200-clk-main";
>>> +        interrupt-parent = <&pmc>;
>>> +        interrupts = <AT91_PMC_MOSCS IRQ_TYPE_LEVEL_HIGH>;
>>
>> Ditto
>>
>>> +        #clock-cells = <0>;
>>> +        clocks = <&ck32k>;
>>> +        clock-frequency = <18432000>;
>>> +    };
>>> +
>>> +Required properties for master clock:
>>> +- interrupt-parent : must reference the PMC node.
>>> +- interrupts : shall be set to "<AT91_PMC_MCKRDY IRQ_TYPE_LEVEL_HIGH>".
>>
>> Ditto
>>
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the master clock sources (see atmel datasheet)
>>> phandles.
>>> +    e.g. "<&ck32k>, <&main>, <&plla>, <&pllb>".
>>> +- atmel,clk-output-range : minimum and maximum clock frequency (two u32
>>> +               fields).
>>> +       e.g. output = <0 133000000>; <=> 0 to 133MHz.
>>> +- atmel,clk-divisors : master clock divisors table (four u32 fields).
>>> +        0 <=> reserved value.
>>> +        e.g. divisors = <1 2 4 6>;
>>> +- atmel,master-clk-have-div3-pres : some SoC use the reserved value
>>> 7 in the
>>> +                    PRES field as CLOCK_DIV3 (e.g sam9x5).
>>
>> I will check with care the master clock driver as this one is pretty
>> picky about changes that could affect it! Note that in previous clock
>> implementation we did not touched the MCK configuration, we were only
>> reading it...
>>
>> Anyway, let's keep this binding but make sure that driver is written
>> with extreme care ;-)
>>
>>> +
>>> +For example:
>>> +    mck: mck {
>>> +        compatible = "atmel,at91rm9200-clk-master";
>>> +        interrupt-parent = <&pmc>;
>>> +        interrupts = <AT91_PMC_MCKRDY IRQ_TYPE_LEVEL_HIGH>;
>>> +        #clock-cells = <0>;
>>> +        atmel,clk-output-range = <0 133000000>;
>>> +        atmel,clk-divisors = <1 2 4 0>;
>>> +    };
>>> +
>>> +Required properties for peripheral clocks:
>>> +- #clock-cells : from common clock binding; shall be set to 1. The
>>> second cell
>>> +    is used to encode the peripheral id. Peripheral ids are defined in
>>> +    atmel's SoC datasheets.
>>> +- clocks : shall be the master clock phandle.
>>> +    e.g. clocks = <&mck>;
>>> +- name: device tree node describing a specific system clock.
>>> +    * atmel,clk-id: peripheral id. Peripheral id macros should be used.
>>
>> No. Please use raw numbers. We will not switch to macros for these
>> peripheral IDs.
> Sure, I'll change this.
>>
>>> +    * atmel,clk-default-divisor (optional, only available for
>>> +      "atmel,at91sam9x5-clk-peripheral"): sam9x5 and sama5d3 SoC
>>> provides
>>> +      configurable peripheral clock divisor. If you define this
>>> property
>>> +      (u32), the default divisor will be applied when enabling
>>> +      peripheral clock. If not provided the peripheral clock is not
>>> +      divided.
>>> +
>>> +For example:
>>> +    periph: periphck {
>>> +        compatible = "atmel,at91sam9x5-clk-peripheral";
>>> +        #clock-cells = <1>;
>>> +        clocks = <&mck>;
>>> +
>>> +        pioA_clk {
>>> +            atmel,clk-id = <AT91SAM9X5_ID_PIOA>;
>>
>> Ditto.
>>
>>> +            atmel,clk-default-divisor = <1>;
>>> +        };
>>> +
>>> +        pioB_clk {
>>> +            atmel,clk-id = <AT91SAM9X5_ID_PIOB>;
>>> +            atmel,clk-default-divisor = <2>;
>>> +        };
>>> +    };
>>> +
>>> +
>>> +Required properties for pll clocks:
>>> +- interrupt-parent : must reference the PMC node.
>>> +- interrupts : shall be set to "<AT91_PMC_LOCKA IRQ_TYPE_LEVEL_HIGH>".
>>
>> Ditto
>>
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the main clock phandle.
>>> +- atmel,clk-id : pll id. PLL id macros should be used.
>>
>> No macros here, simply raw numbers. So this mean that we must have
>> some documentation of these numbers.
>>
>>> +- atmel,clk-input-range : minimum and maximum source clock frequency
>>> (two u32
>>> +              fields).
>>> +      e.g. input = <1 32000000>; <=> 1 to 32MHz.
>>> +- #atmel,pll-clk-output-range-cells : number of cells reserved for
>>> pll output
>>> +                      range description. Sould be set to 2, 3
>>> +                      or 4.
>>> +    * 1st and 2nd cells represent the frequency range (min-max).
>>> +    * 3rd cell is optional and represents the OUT field value for
>>> the given
>>> +      range.
>>> +    * 4th cell is optional and represents the ICPLL field (PLLICPR
>>> +      register)
>>> +- atmel,pll-clk-output-ranges : pll output frequency ranges +
>>> optional parameter
>>> +                depending on #atmel,pll-output-range-cells
>>> +                property value.
>>> +
>>> +For example:
>>> +    plla: pllack {
>>> +        compatible = "atmel,at91sam9g45-clk-pll";
>>> +        interrupt-parent = <&pmc>;
>>> +        interrupts = <AT91_PMC_LOCKA IRQ_TYPE_LEVEL_HIGH>;
>>> +        #clock-cells = <0>;
>>> +        clocks = <&main>;
>>> +        atmel,clk-id = <AT91_PLLA_CLK>;
>>> +        atmel,clk-input-range = <2000000 32000000>;
>>> +        #atmel,pll-clk-output-range-cells = <4>;
>>> +        atmel,pll-clk-output-ranges = <74500000 800000000 0 0
>>> +                           69500000 750000000 1 0
>>> +                           64500000 700000000 2 0
>>> +                           59500000 650000000 3 0
>>> +                           54500000 600000000 0 1
>>> +                           49500000 550000000 1 1
>>> +                           44500000 500000000 2 1
>>> +                           40000000 450000000 3 1>;
>>> +    };
>>> +
>>> +Required properties for plldiv clocks:
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the plla clock phandle.
>>> +
>>> +For example:
>>> +    plladiv: plladivck {
>>> +        compatible = "atmel,at91sam9x5-clk-plldiv";
>>> +        #clock-cells = <0>;
>>> +        clocks = <&plla>;
>>> +    };
>>
>> Maybe a little explanation about this clock. It is a fixed divided
>> (how many times?) clock issued from the specified clock.
>
> It is a fixed clock divider (by 2) and AFAIK clk parent must be plla.
> I'll add more precision about this clk.
>
>>
>>> +
>>> +Required properties for programmable clocks:
>>> +- interrupt-parent : must reference the PMC node.
>>> +- #clock-cells : from common clock binding; shall be set to 1. The
>>> second cell
>>> +    is used to encode the programmable clock id.
>>> +    Peripheral ids are in atmel's SoC
>>> +    datasheets.
>>> +- clocks : shall be the programmable clock source phandles.
>>> +    e.g. clocks = <&clk32k>, <&main>, <&plla>, <&pllb>;
>>> +- name: device tree node describing a specific prog clock.
>>> +    * atmel,clk-id : programmable clock id (register offset from  PCKx
>>> +             register).
>>> +    * interrupts : shall be set to
>>> +               "<AT91_PMC_PCKRDY(id) IRQ_TYPE_LEVEL_HIGH>".
>>
>> Ditto
>>
>>> +
>>> +For example:
>>> +    prog: progck {
>>> +        compatible = "atmel,at91sam9g45-clk-programmable";
>>> +        interrupt-parent = <&pmc>;
>>> +        #clock-cells = <1>;
>>> +        clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>;
>>> +
>>> +        prog0 {
>>> +            atmel,clk-id = <0>;
>>> +            interrupts = <AT91_PMC_PCKRDY(0) IRQ_TYPE_LEVEL_HIGH>;
>>
>> Ditto
>>
>>> +        };
>>> +
>>> +        prog1 {
>>> +            atmel,clk-id = <1>;
>>> +            interrupts = <AT91_PMC_PCKRDY(1) IRQ_TYPE_LEVEL_HIGH>;
>>> +        };
>>> +    };
>>> +
>>> +
>>> +Required properties for smd clock:
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the smd clock source phandles.
>>> +    e.g. clocks = <&plladiv>, <&utmi>;
>>> +
>>> +For example:
>>> +    smd: smdck {
>>> +        compatible = "atmel,at91sam9x5-clk-smd";
>>> +        #clock-cells = <0>;
>>> +        clocks = <&plladiv>, <&utmi>;
>>> +    };
>>> +
>>> +Required properties for system clocks:
>>> +- #clock-cells : from common clock binding; shall be set to 1. The
>>> second cell
>>> +    is used to encode the system clock id (bit used in SCER/SCDR
>>> register).
>>> +- name: device tree node describing a specific system clock.
>>> +    * id: system clock id (bit position in SCER/SCDR/SCSR registers).
>>> +          System clock id macros should be used.
>>
>> Ditto
>>
>>> +
>>> +For example:
>>> +    system: systemck {
>>> +        compatible = "atmel,at91rm9200-clk-system";
>>> +        #clock-cells = <1>;
>>> +
>>> +        ddrck {
>>> +            atmel,clk-id = <AT91_DDRCK_SYS_CLK>;
>>> +        };
>>> +
>>> +        uhpck {
>>> +            atmel,clk-id = <AT91_UHP_SYS_CLK>;
>>> +        };
>>> +
>>> +        udpck {
>>> +            atmel,clk-id = <AT91_UDP_SYS_CLK>;
>>> +        };
>>> +    };
>>> +
>>> +
>>> +Required properties for usb clock:
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the smd clock source phandles.
>>> +    e.g. clocks = <&pllb>;
>>> +- atmel,clk-divisors (only available for "atmel,at91rm9200-clk-usb"):
>>> +    usb clock divisor table.
>>> +    e.g. divisors = <1 2 4 0>;
>>> +- atmel,usb-clk-src0-unused (only available for
>>> "atmel,at91sam9x5-clk-usb"):
>>> +    Some SoC (sam9n12) use usb source 0 to disable the usb clock.
>>
>> I am not sure that we should use a special case for this device.
>> The enable/disable is still done by system clock register set.
>>
>> It is true that this bit is defined differently but just because the
>> only source for this clock is pllb.
>
> Yes, but at least, I need to know that I must add one to the clock
> parent id when I set the USBS field in the PMC_USB register.
> Or I can drop the atmel,usb-clk-src0-unused property and  just add a new
> "atmel,at91sam9n12-clk-usb" compatible string,
> which might be a better solution here.
>
> Tell me what you'd prefer.

Yep, that is what I was thinking about: use a specific 
"atmel,at91sam9n12-clk-usb" compatible string.

>>
>>> +
>>> +For example:
>>> +    usb: usbck {
>>> +        compatible = "atmel,at91sam9x5-clk-usb";
>>> +        #clock-cells = <0>;
>>> +        clocks = <&plladiv>, <&utmi>;
>>> +    };
>>> +
>>> +    usb: usbck {
>>> +        compatible = "atmel,at91rm9200-clk-usb";
>>> +        #clock-cells = <0>;
>>> +        clocks = <&pllb>;
>>> +        atmel,clk-divisors = <1 2 4 0>;
>>> +    };
>>> +
>>> +
>>> +Required properties for utmi clock:
>>> +- interrupt-parent : must reference the PMC node.
>>> +- interrupts : shall be set to "<AT91_PMC_LOCKU IRQ_TYPE_LEVEL_HIGH>".
>>> +- #clock-cells : from common clock binding; shall be set to 0.
>>> +- clocks : shall be the main clock source phandle.
>>> +
>>> +For example:
>>> +    utmi: utmick {
>>> +        compatible = "atmel,at91sam9x5-clk-utmi";
>>> +        interrupt-parent = <&pmc>;
>>> +        interrupts = <AT91_PMC_LOCKU IRQ_TYPE_LEVEL_HIGH>;
>>> +        #clock-cells = <0>;
>>> +        clocks = <&main>;
>>> +    };
>>>
>>
>> Many things in this patch that will have incident in driver code. I
>> will try to be coherent when I review the driver patches ;-)
>>
>> Anyway, all this seem good!
>>
>> Bye,
>
> Thanks for the detailed review.
>
>
>
>


-- 
Nicolas Ferre