Re: [PATCH v1 2/2] dt-bindings: clock: rockchip: Add support for clk input / output switch

[Rob Herring <robh@kernel.org>]

On Mon, 25 Mar 2024 12:16:30 +0800, Sugar Zhang wrote:
> This patch add support switch for clk-bidirection which located
> at GRF, such as SAIx_MCLK_{IN OUT} which share the same pin.
> and these config maybe located in many pieces of GRF,
> which hard to addressed in one single clk driver. so, we add
> this simple helper driver to address this situation.
> 
> In order to simplify implement and usage, and also for safety
> clk usage (avoid high freq glitch), we set all clk out as disabled
> (which means Input default for clk-bidrection) in the pre-stage,
> such boot-loader or init by HW default. And then set a safety freq
> before enable clk-out, such as "assign-clock-rates" or clk_set_rate
> in drivers.
> 
> e.g.
> 
> 1. mclk{out,in}_sai0 define:
> 
>   mclkin_sai0: mclkin-sai0 {
>       compatible = "fixed-clock";
>       #clock-cells = <0>;
>       clock-frequency = <12288000>;
>       clock-output-names = "mclk_sai0_from_io";
>   };
> 
>   mclkout_sai0: mclkout-sai0@ff040070 {
>       compatible = "rockchip,clk-out";
>       reg = <0 0xff040070 0 0x4>;
>       clocks = <&cru MCLK_SAI0_OUT2IO>;
>       #clock-cells = <0>;
>       clock-output-names = "mclk_sai0_to_io";
>       rockchip,bit-shift = <4>;
>       //example with PD if reg access needed
>       power-domains = <&power RK3562_PD_VO>;
>   };
> 
> Note:
> 
> clock-output-names of mclkin_sai0 should equal to strings in drivers. such as:
> 
> drivers/clk/rockchip/clk-rk3562.c:
> PNAME(clk_sai0_p) = { "clk_sai0_src", "clk_sai0_frac", "xin_osc0_half", "mclk_sai0_from_io" };
> 
> 2. mclkout_sai0 usage:
> 
>   &ext_codec {
>       clocks = <&mclkout_sai0>;
>       clock-names = "mclk";
>       assigned-clocks = <&mclkout_sai0>;
>       assigned-clock-rates = <12288000>;
>       pinctrl-names = "default";
>       pinctrl-0 = <&i2s0m0_mclk>;
>   };
> 
>   clk_summary on sai0 work:
> 
>   cat /sys/kernel/debug/clk/clk_summary | egrep "pll|sai0"
> 
>   clk_sai0_src                1        1        0  1188000000          0     0  50000
>     clk_sai0_frac             1        1        0    12288000          0     0  50000
>       clk_sai0                1        1        0    12288000          0     0  50000
>         mclk_sai0             1        1        0    12288000          0     0  50000
>           mclk_sai0_out2io    1        1        0    12288000          0     0  50000
>             mclk_sai0_to_io   1        1        0    12288000          0     0  50000
> 
>   example with PD if reg access needed:
> 
>   * PD status when mclk_sai0_to_io on:
> 
>   cat /sys/kernel/debug/pm_genpd/pm_genpd_summary
> 
>   domain                          status          children
>     /device                                                runtime status
>   ----------------------------------------------------------------------
>   ...
> 
>   vo                              on
>     /devices/platform/clocks/ff040070.mclkout-sai0         active
>   ...
> 
>   * PD status when mclk_sai0_to_io off:
> 
>   cat /sys/kernel/debug/pm_genpd/pm_genpd_summary
> 
>   domain                          status          children
>     /device                                                runtime status
>   ----------------------------------------------------------------------
>   ...
> 
>   vo                              off-0
>     /devices/platform/clocks/ff040070.mclkout-sai0         suspended
>   ...
> 
> 3. mclkin_sai0 usage:
> 
>   please override freq of mclkin as the real external clkin, such as:
> 
>   &mclkin_sai0 {
>       clock-frequency = <24576000>;
>   }
> 
>   &ext_codec {
>       clocks = <&mclkin_sai0>;
>       clock-names = "mclk";
>       assigned-clocks = <&cru CLK_SAI0>;
>       assigned-clock-parents = <&mclkin_sai0>;
>       pinctrl-names = "default";
>       pinctrl-0 = <&i2s0m0_mclk>;
>   };
> 
>   clk_summary on sai0 work:
> 
>   cat /sys/kernel/debug/clk/clk_summary | egrep "pll|sai0"
> 
>   mclk_sai0_from_io          1        1        0    12288000          0     0  50000
>     clk_sai0                 1        1        0    12288000          0     0  50000
>       mclk_sai0              1        1        0    12288000          0     0  50000
>         mclk_sai0_out2io     0        0        0    12288000          0     0  50000
>           mclk_sai0_to_io    0        0        0    12288000          0     0  50000
> 
> Signed-off-by: Sugar Zhang <sugar.zhang@rock-chips.com>
> ---
> 
>  .../bindings/clock/rockchip,clk-out.yaml           | 107 +++++++++++++++++++++
>  1 file changed, 107 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/clock/rockchip,clk-out.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/clock/rockchip,clk-out.yaml: title: 'Rockchip Clock Out Control Module Binding' should not be valid under {'pattern': '([Bb]inding| [Ss]chema)'}
	hint: Everything is a binding/schema, no need to say it. Describe what hardware the binding is for.
	from schema $id: http://devicetree.org/meta-schemas/base.yaml#
Error: Documentation/devicetree/bindings/clock/rockchip,clk-out.example.dts:28.28-29 syntax error
FATAL ERROR: Unable to parse input tree
make[2]: *** [scripts/Makefile.lib:427: Documentation/devicetree/bindings/clock/rockchip,clk-out.example.dtb] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1430: dt_binding_check] Error 2
make: *** [Makefile:240: __sub-make] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/1711340191-69588-2-git-send-email-sugar.zhang@rock-chips.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.