[PATCH 1/2] PM: EM: fix kernel-doc comments

[PATCH 1/2] PM: EM: fix kernel-doc comments

[Lukasz Luba]

Fix the kernel-doc comments for the improved Energy Model documentation.

Signed-off-by: Lukasz Luba <lukasz.luba@arm.com>
---
 include/linux/energy_model.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/include/linux/energy_model.h b/include/linux/energy_model.h
index 1834752c5617..39dcadd492b5 100644
--- a/include/linux/energy_model.h
+++ b/include/linux/energy_model.h
@@ -11,7 +11,7 @@
 #include <linux/types.h>
 
 /**
- * em_perf_state - Performance state of a performance domain
+ * struct em_perf_state - Performance state of a performance domain
  * @frequency:	The frequency in KHz, for consistency with CPUFreq
  * @power:	The power consumed at this level (by 1 CPU or by a registered
  *		device). It can be a total power: static and dynamic.
@@ -25,7 +25,7 @@ struct em_perf_state {
 };
 
 /**
- * em_perf_domain - Performance domain
+ * struct em_perf_domain - Performance domain
  * @table:		List of performance states, in ascending order
  * @nr_perf_states:	Number of performance states
  * @milliwatts:		Flag indicating the power values are in milli-Watts
@@ -103,12 +103,12 @@ void em_dev_unregister_perf_domain(struct device *dev);
 
 /**
  * em_cpu_energy() - Estimates the energy consumed by the CPUs of a
-		performance domain
+ *		performance domain
  * @pd		: performance domain for which energy has to be estimated
  * @max_util	: highest utilization among CPUs of the domain
  * @sum_util	: sum of the utilization of all CPUs in the domain
  * @allowed_cpu_cap	: maximum allowed CPU capacity for the @pd, which
-			  might reflect reduced frequency (due to thermal)
+ *			  might reflect reduced frequency (due to thermal)
  *
  * This function must be used only for CPU devices. There is no validation,
  * i.e. if the EM is a CPU type and has cpumask allocated. It is called from
-- 
2.17.1

[PATCH 2/2] Documentation: power: include kernel-doc in Energy Model doc

[Lukasz Luba]

Improve the existing documentation of the Energy Model and add kernel-doc
comments. This extends an API description and helps better understanding
the usage.

Signed-off-by: Lukasz Luba <lukasz.luba@arm.com>
---
 Documentation/power/energy-model.rst | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst
index 60ac091d3b0d..8a2788afe89b 100644
--- a/Documentation/power/energy-model.rst
+++ b/Documentation/power/energy-model.rst
@@ -101,8 +101,7 @@ subsystems which use EM might rely on this flag to check if all EM devices use
 the same scale. If there are different scales, these subsystems might decide
 to: return warning/error, stop working or panic.
 See Section 3. for an example of driver implementing this
-callback, and kernel/power/energy_model.c for further documentation on this
-API.
+callback, or Section 2.4 for further documentation on this API
 
 
 2.3 Accessing performance domains
@@ -123,7 +122,17 @@ em_cpu_energy() API. The estimation is performed assuming that the schedutil
 CPUfreq governor is in use in case of CPU device. Currently this calculation is
 not provided for other type of devices.
 
-More details about the above APIs can be found in include/linux/energy_model.h.
+More details about the above APIs can be found in ``<linux/energy_model.h>``
+or in Section 2.4
+
+
+2.4 Description details of this API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. kernel-doc:: include/linux/energy_model.h
+   :internal:
+
+.. kernel-doc:: kernel/power/energy_model.c
+   :export:
 
 
 3. Example driver
-- 
2.17.1

Re: [PATCH 1/2] PM: EM: fix kernel-doc comments

[Rafael J. Wysocki]

On Mon, Sep 6, 2021 at 10:46 AM Lukasz Luba <lukasz.luba@arm.com> wrote:
>
> Fix the kernel-doc comments for the improved Energy Model documentation.
>
> Signed-off-by: Lukasz Luba <lukasz.luba@arm.com>
> ---
>  include/linux/energy_model.h | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/include/linux/energy_model.h b/include/linux/energy_model.h
> index 1834752c5617..39dcadd492b5 100644
> --- a/include/linux/energy_model.h
> +++ b/include/linux/energy_model.h
> @@ -11,7 +11,7 @@
>  #include <linux/types.h>
>
>  /**
> - * em_perf_state - Performance state of a performance domain
> + * struct em_perf_state - Performance state of a performance domain
>   * @frequency: The frequency in KHz, for consistency with CPUFreq
>   * @power:     The power consumed at this level (by 1 CPU or by a registered
>   *             device). It can be a total power: static and dynamic.
> @@ -25,7 +25,7 @@ struct em_perf_state {
>  };
>
>  /**
> - * em_perf_domain - Performance domain
> + * struct em_perf_domain - Performance domain
>   * @table:             List of performance states, in ascending order
>   * @nr_perf_states:    Number of performance states
>   * @milliwatts:                Flag indicating the power values are in milli-Watts
> @@ -103,12 +103,12 @@ void em_dev_unregister_perf_domain(struct device *dev);
>
>  /**
>   * em_cpu_energy() - Estimates the energy consumed by the CPUs of a
> -               performance domain
> + *             performance domain
>   * @pd         : performance domain for which energy has to be estimated
>   * @max_util   : highest utilization among CPUs of the domain
>   * @sum_util   : sum of the utilization of all CPUs in the domain
>   * @allowed_cpu_cap    : maximum allowed CPU capacity for the @pd, which
> -                         might reflect reduced frequency (due to thermal)
> + *                       might reflect reduced frequency (due to thermal)
>   *
>   * This function must be used only for CPU devices. There is no validation,
>   * i.e. if the EM is a CPU type and has cpumask allocated. It is called from
> --

Applied as 5.15-rc material along with the [2/2], thanks!

Re: [PATCH 1/2] PM: EM: fix kernel-doc comments

[Lukasz Luba]

On 9/7/21 8:22 PM, Rafael J. Wysocki wrote:
> On Mon, Sep 6, 2021 at 10:46 AM Lukasz Luba <lukasz.luba@arm.com> wrote:
>>

> 
> Applied as 5.15-rc material along with the [2/2], thanks!
> 

Thank you Rafael!

Regards,
Lukasz