Re: [PATCH v2 14/17] Documentation: EM: Add a new section about the design

[Dietmar Eggemann <dietmar.eggemann@arm.com>]

On 12/05/2023 11:57, Lukasz Luba wrote:
> Add a new section 'Design' which covers the information about Energy
> Model. It contains the design decisions, describes models and how they
> reflect the reality. Add description of the basic const. EM. Change the
> other section IDs.

I would vote for coalescing the 4 doc patches into 1.

> 
> Signed-off-by: Lukasz Luba <lukasz.luba@arm.com>
> ---
>  Documentation/power/energy-model.rst | 36 +++++++++++++++++++++-------
>  1 file changed, 27 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst
> index ef341be2882b..e97c7f18d8bd 100644
> --- a/Documentation/power/energy-model.rst
> +++ b/Documentation/power/energy-model.rst
> @@ -72,16 +72,34 @@ required to have the same micro-architecture. CPUs in different performance
>  domains can have different micro-architectures.
>  
>  
> -2. Core APIs
> +2. Design
> +-----------------
> +
> +2.1 Basic EM
> +^^^^^^^^^^^^

Can we make sure that people get the relation between 'basic' and
'default' easier?

It should be obvious that `pd->default_table->state` refers to this
`basic (const.) EM. Using the same identifier always helps in this
situation.

> +
> +The basic EM is built around const. power information for each performance
> +state. This model can be derived based on power measurements of the device
> +e.g. CPU while running some benchmark. The benchmark might be integer heavy
> +or floating point computation with a data set fitting into the CPU cache or
> +registers. Bare in mind that this model might not be covering all possible
> +workloads running on CPUs. Thus, please run a few different benchmarks and
> +verify with some real workloads your power model values. The power variation
> +due to the workload instruction mix and data set is not modeled.
> +Also static power which can change during runtime due to variation of SOC
> +temperature is not modeled in EM.
> +
> +
> +3. Core APIs
>  ------------
>  
> -2.1 Config options
> +3.1 Config options
>  ^^^^^^^^^^^^^^^^^^
>  
>  CONFIG_ENERGY_MODEL must be enabled to use the EM framework.
>  
>  
> -2.2 Registration of performance domains
> +3.2 Registration of performance domains
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  Registration of 'advanced' EM
> @@ -110,8 +128,8 @@ The last argument 'microwatts' is important to set with correct value. Kernel
>  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, or Section 2.4 for further documentation on this API
> +See Section 4. for an example of driver implementing this
> +callback, or Section 3.4 for further documentation on this API
>  
>  Registration of EM using DT
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -156,7 +174,7 @@ The EM which is registered using this method might not reflect correctly the
>  physics of a real device, e.g. when static power (leakage) is important.
>  
>  
> -2.3 Accessing performance domains
> +3.3 Accessing performance domains
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
>  There are two API functions which provide the access to the energy model:
> @@ -175,10 +193,10 @@ 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 ``<linux/energy_model.h>``
> -or in Section 2.4
> +or in Section 3.4
>  
>  
> -2.4 Description details of this API
> +3.4 Description details of this API
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  .. kernel-doc:: include/linux/energy_model.h
>     :internal:
> @@ -187,7 +205,7 @@ or in Section 2.4
>     :export:
>  
>  
> -3. Example driver
> +4. Example driver
>  -----------------
>  
>  The CPUFreq framework supports dedicated callback for registering