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.
Signed-off-by: Lukasz Luba <[email protected]>
---
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
+^^^^^^^^^^^^
+
+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
--
2.25.1
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 <[email protected]>
> ---
> 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
On 5/30/23 11:33, Dietmar Eggemann wrote:
> 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.
OK, I can make that. I will be a big one patch, though.
>
>>
>> Signed-off-by: Lukasz Luba <[email protected]>
>> ---
>> 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.
OK, how about adding this:
"The basic EM is built around const. power information for each
performance state, which is accessible in:
'dev->em_pd->default_table->state'. This model can be derived based..."
>
>> +
>> +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.
>> +
>> +