[v2,06/48] dt-bindings: clock: tegra: Document clocks sub-node

Document "clocks" sub-node which describes Tegra SoC clocks that require
a higher voltage of the core power domain in order to operate properly on
a higher rates.

Signed-off-by: Dmitry Osipenko <digetx@gmail.com>
---
 .../bindings/clock/nvidia,tegra20-car.txt     | 26 +++++++++++++++++++
 .../bindings/clock/nvidia,tegra30-car.txt     | 26 +++++++++++++++++++
 2 files changed, 52 insertions(+)

On Thu, Dec 17, 2020 at 09:05:56PM +0300, Dmitry Osipenko wrote:
> Document "clocks" sub-node which describes Tegra SoC clocks that require
> a higher voltage of the core power domain in order to operate properly on
> a higher rates.

Seems like an odd reason to have a bunch of child nodes. It very much 
seems like a problem you'd need to solve after you design the binding 
which should be fixed within the kernel.

This is also above my threshold for 'convert to schema' first...

> 
> Signed-off-by: Dmitry Osipenko <digetx@gmail.com>
> ---
>  .../bindings/clock/nvidia,tegra20-car.txt     | 26 +++++++++++++++++++
>  .../bindings/clock/nvidia,tegra30-car.txt     | 26 +++++++++++++++++++
>  2 files changed, 52 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.txt b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.txt
> index 6c5901b503d0..353354477785 100644
> --- a/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.txt
> +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra20-car.txt
> @@ -19,6 +19,16 @@ Required properties :
>    In clock consumers, this cell represents the bit number in the CAR's
>    array of CLK_RST_CONTROLLER_RST_DEVICES_* registers.
>  
> +Optional child sub-node "clocks" should contain nodes matching the clocks
> +on the Tegra SoC. Refer to Tegra TRM for mode details on the clock nodes.
> +
> +Required properties :
> +- compatible : Should be "nvidia,tegra20-clock".
> +- operating-points-v2: See ../bindings/opp/opp.txt for details.
> +- clocks : Should contain clock which corresponds to the node.
> +- power-domains: Phandle to a power domain node as described by generic
> +                 PM domain bindings.
> +
>  Example SoC include file:
>  
>  / {
> @@ -27,6 +37,22 @@ Example SoC include file:
>  		reg = <0x60006000 0x1000>;
>  		#clock-cells = <1>;
>  		#reset-cells = <1>;
> +
> +		clocks {
> +			hdmi {
> +				compatible = "nvidia,tegra20-clock";
> +				operating-points-v2 = <&hdmi_opp_table>;
> +				clocks = <&tegra_car TEGRA20_CLK_HDMI>;
> +				power-domains = <&domain>;
> +			};
> +
> +			pll_m {
> +				compatible = "nvidia,tegra20-clock";
> +				operating-points-v2 = <&pll_m_opp_table>;
> +				clocks = <&tegra_car TEGRA20_CLK_PLL_M>;
> +				power-domains = <&domain>;
> +			};
> +		};
>  	};
>  
>  	usb@c5004000 {
> diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra30-car.txt b/Documentation/devicetree/bindings/clock/nvidia,tegra30-car.txt
> index 63618cde12df..bc7bbdaa9d3f 100644
> --- a/Documentation/devicetree/bindings/clock/nvidia,tegra30-car.txt
> +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra30-car.txt
> @@ -19,6 +19,16 @@ Required properties :
>    In clock consumers, this cell represents the bit number in the CAR's
>    array of CLK_RST_CONTROLLER_RST_DEVICES_* registers.
>  
> +Optional child sub-node "clocks" should contain nodes matching the clocks
> +on the Tegra SoC. Refer to Tegra TRM for mode details on the clock nodes.
> +
> +Required properties :
> +- compatible : Should be "nvidia,tegra30-clock".
> +- operating-points-v2: See ../bindings/opp/opp.txt for details.
> +- clocks : Should contain clock which corresponds to the node.
> +- power-domains: Phandle to a power domain node as described by generic
> +                 PM domain bindings.
> +
>  Example SoC include file:
>  
>  / {
> @@ -31,6 +41,22 @@ Example SoC include file:
>  
>  	usb@c5004000 {
>  		clocks = <&tegra_car TEGRA30_CLK_USB2>;
> +
> +		clocks {
> +			hdmi {
> +				compatible = "nvidia,tegra30-clock";
> +				operating-points-v2 = <&hdmi_opp_table>;
> +				clocks = <&tegra_car TEGRA30_CLK_HDMI>;
> +				power-domains = <&domain>;
> +			};
> +
> +			pll_m {
> +				compatible = "nvidia,tegra30-clock";
> +				operating-points-v2 = <&pll_m_opp_table>;
> +				clocks = <&tegra_car TEGRA30_CLK_PLL_M>;
> +				power-domains = <&domain>;
> +			};
> +		};
>  	};
>  };
>  
> -- 
> 2.29.2
>

22.12.2020 03:14, Rob Herring пишет:
> On Thu, Dec 17, 2020 at 09:05:56PM +0300, Dmitry Osipenko wrote:
>> Document "clocks" sub-node which describes Tegra SoC clocks that require
>> a higher voltage of the core power domain in order to operate properly on
>> a higher rates.
> 
> Seems like an odd reason to have a bunch of child nodes. It very much 
> seems like a problem you'd need to solve after you design the binding 
> which should be fixed within the kernel.

The reason is that multiple root SoC PLL clocks need to have individual
OPP table because proper voltage should be maintained for these clocks
based on the clock rate.

Some of the clocks do not belong to any specific device and there is a
need to specify the OPP table for them. Each child node represents an
individual clock with the clock's OPP table and power domain.

Some clocks belong to a specific device, but don't require high voltages
and it's very convenient that clk device could manage voltage for these
clocks, instead of populating each device with OPP support (PWM, MMC and
etc).

I'll update the commit message with a better explanation in v3.

> This is also above my threshold for 'convert to schema' first...

Alright, will convert it in v3.