[PATCH] clk: add function documentation for clk_hw_round_rate()

[PATCH] clk: add function documentation for clk_hw_round_rate()

[Sarang Mairal]

Information about usage and prerequisites for this API.

Signed-off-by: Sarang Mairal <sarangmairal@gmail.com>
---
 drivers/clk/clk.c | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 407f6919604c..9cb9bc67a165 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -1400,6 +1400,19 @@ int __clk_determine_rate(struct clk_hw *hw, struct clk_rate_request *req)
 }
 EXPORT_SYMBOL_GPL(__clk_determine_rate);
 
+/**
+ * clk_hw_round_rate - round the given rate for a hw clk
+ * @hw: the hw clk for which we are rounding a rate
+ * @rate: the rate which is to be rounded
+ *
+ * Takes in a rate as input and rounds it to a rate that the clk can actually
+ * use which is then returned. If clk doesn't support round_rate operation
+ * then the parent rate is returned.
+ *
+ * Useful for clk providers to call from within clk_ops such as .round_rate,
+ * .determine_rate. Requires prepare_lock to be held before calling this
+ * function.
+ */
 unsigned long clk_hw_round_rate(struct clk_hw *hw, unsigned long rate)
 {
 	int ret;
-- 
2.17.1

Re: [PATCH] clk: add function documentation for clk_hw_round_rate()

[Stephen Boyd]

Quoting Sarang Mairal (2020-06-10 08:17:44)
> Information about usage and prerequisites for this API.
> 
> Signed-off-by: Sarang Mairal <sarangmairal@gmail.com>
> ---
>  drivers/clk/clk.c | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> index 407f6919604c..9cb9bc67a165 100644
> --- a/drivers/clk/clk.c
> +++ b/drivers/clk/clk.c
> @@ -1400,6 +1400,19 @@ int __clk_determine_rate(struct clk_hw *hw, struct clk_rate_request *req)
>  }
>  EXPORT_SYMBOL_GPL(__clk_determine_rate);
>  
> +/**
> + * clk_hw_round_rate - round the given rate for a hw clk
> + * @hw: the hw clk for which we are rounding a rate
> + * @rate: the rate which is to be rounded
> + *
> + * Takes in a rate as input and rounds it to a rate that the clk can actually
> + * use which is then returned. If clk doesn't support round_rate operation
> + * then the parent rate is returned.
> + *
> + * Useful for clk providers to call from within clk_ops such as .round_rate,
> + * .determine_rate. Requires prepare_lock to be held before calling this
> + * function.

I think we can use the 'Return:' and the 'Context:' sections in
kernel-doc[1]. Can you reword using those please?

> + */
>  unsigned long clk_hw_round_rate(struct clk_hw *hw, unsigned long rate)
>  {
>         int ret;

[1] Documentation/doc-guide/kernel-doc.rst

Re: [PATCH] clk: add function documentation for clk_hw_round_rate()

[Sarang Mairal]

> I think we can use the 'Return:' and the 'Context:' sections in
> kernel-doc[1]. Can you reword using those please?
Yes, nice suggestion! Thanks.

Hopefully v2 addresses your expectation.

-Regards,
Sarang.

[PATCH v2] clk: add function documentation for clk_hw_round_rate()

[Sarang Mairal]

Information about usage and prerequisites for this API.

Signed-off-by: Sarang Mairal <sarangmairal@gmail.com>
---
 drivers/clk/clk.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 407f6919604c..da3182404934 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -1400,6 +1400,21 @@ int __clk_determine_rate(struct clk_hw *hw, struct clk_rate_request *req)
 }
 EXPORT_SYMBOL_GPL(__clk_determine_rate);
 
+/**
+ * clk_hw_round_rate() - round the given rate for a hw clk
+ * @hw: the hw clk for which we are rounding a rate
+ * @rate: the rate which is to be rounded
+ *
+ * Takes in a rate as input and rounds it to a rate that the clk can actually
+ * use.
+ *
+ * Context: prepare_lock must be held.
+ *          For clk providers to call from within clk_ops such as .round_rate,
+ *          .determine_rate.
+ *
+ * Return: returns rounded rate of hw clk if clk supports round_rate operation
+ *         else returns the parent rate.
+ */
 unsigned long clk_hw_round_rate(struct clk_hw *hw, unsigned long rate)
 {
 	int ret;
-- 
2.17.1

Re: [PATCH v2] clk: add function documentation for clk_hw_round_rate()

[Stephen Boyd]

Quoting Sarang Mairal (2020-06-10 19:19:41)
> Information about usage and prerequisites for this API.
> 
> Signed-off-by: Sarang Mairal <sarangmairal@gmail.com>
> ---

Applied to clk-next