2.1 Config options¶

CONFIG_ENERGY_MODEL must be enabled to use the EM framework.

2.2 Registration of performance domains¶

int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,              struct em_data_callback *cb, cpumask_t *cpus, bool microwatts);

Power = C * V^2 * f

2.3 Accessing performance domains¶

There are two API functions which provide the access to the energy model:em_cpu_get() which takes CPU id as an argument andem_pd_get() with devicepointer as an argument. It depends on the subsystem which interface it isgoing to use, but in case of CPU devices both functions return the sameperformance domain.

Subsystems interested in the energy model of a CPU can retrieve it using theem_cpu_get() API. The energy model tables are allocated once upon creation ofthe performance domains, and kept in memory untouched.

The energy consumed by a performance domain can be estimated using theem_cpu_energy() API. The estimation is performed assuming that the schedutilCPUfreq governor is in use in case of CPU device. Currently this calculation isnot provided for other type of devices.

More details about the above APIs can be found in<linux/energy_model.h>or in Section 2.5

2.4 Runtime modifications¶

Drivers willing to update the EM at runtime should use the following dedicatedfunction to allocate a new instance of the modified EM. The API is listedbelow:

struct em_perf_table __rcu *em_table_alloc(struct em_perf_domain *pd);

This allows to allocate a structure which contains the new EM table withalso RCU and kref needed by the EM framework. The ‘structem_perf_table’contains array ‘structem_perf_state state[]’ which is a list of performancestates in ascending order. That list must be populated by the device driverwhich wants to update the EM. The list of frequencies can be taken fromexisting EM (created during boot). The content in the ‘structem_perf_state’must be populated by the driver as well.

This is the API which does the EM update, using RCU pointers swap:

int em_dev_update_perf_domain(struct device *dev,                      struct em_perf_table __rcu *new_table);

Drivers must provide a pointer to the allocated and initialized new EM‘structem_perf_table’. That new EM will be safely used inside the EM frameworkand will be visible to other sub-systems in the kernel (thermal, powercap).The main design goal for this API is to be fast and avoid extra calculationsor memory allocations at runtime. When pre-computed EMs are available in thedevice driver, then it should be possible to simply reuse them with lowperformance overhead.

In order to free the EM, provided earlier by the driver (e.g. when the moduleis unloaded), there is a need to call the API:

void em_table_free(struct em_perf_table __rcu *table);

It will allow the EM framework to safely remove the memory, when there isno other sub-system using it, e.g. EAS.

To use the power values in other sub-systems (like thermal, powercap) there isa need to call API which protects the reader and provide consistency of the EMtable data:

struct em_perf_state *em_perf_state_from_pd(struct em_perf_domain *pd);

It returns the ‘structem_perf_state’ pointer which is an array of performancestates in ascending order.This function must be called in the RCU read lock section (after thercu_read_lock()). When the EM table is not needed anymore there is a need tocallrcu_real_unlock(). In this way the EM safely uses the RCU read sectionand protects the users. It also allows the EM framework to manage the memoryand free it. More details how to use it can be found in Section 3.2 in theexample driver.

There is dedicated API for device drivers to calculate em_perf_state::costvalues:

int em_dev_compute_costs(struct device *dev, struct em_perf_state *table,                         int nr_states);

These ‘cost’ values from EM are used in EAS. The new EM table should be passedtogether with the number of entries and device pointer. When the computationof the cost values is done properly the return value from the function is 0.The function takes care for right setting of inefficiency for each performancestate as well. It updates em_perf_state::flags accordingly.Then such prepared new EM can be passed to theem_dev_update_perf_domain()function, which will allow to use it.

More details about the above APIs can be found in<linux/energy_model.h>or in Section 3.2 with an example code showing simple implementation of theupdating mechanism in a device driver.

2.5 Description details of this API¶

structem_perf_state¶

Performance state of a performance domain

struct em_perf_state {    unsigned long performance;    unsigned long frequency;    unsigned long power;    unsigned long cost;    unsigned long flags;};

structem_perf_table¶

Performance states table

struct em_perf_table {    struct rcu_head rcu;    struct kref kref;    struct em_perf_state state[];};

structem_perf_domain¶

Performance domain

struct em_perf_domain {    struct em_perf_table  *em_table;    struct list_head node;    int id;    int nr_perf_states;    int min_perf_state;    int max_perf_state;    unsigned long flags;    unsigned long cpus[];};

Description

In case of CPU device, a “performance domain” represents a group of CPUswhose performance is scaled together. All CPUs of a performance domainmust have the same micro-architecture. Performance domains often havea 1-to-1 mapping with CPUFreq policies. In case of other devices thecpusfield is unused.

intem_pd_get_efficient_state(structem_perf_state*table,structem_perf_domain*pd,unsignedlongmax_util)¶

Get an efficient performance state from the EM

unsignedlongem_cpu_energy(structem_perf_domain*pd,unsignedlongmax_util,unsignedlongsum_util,unsignedlongallowed_cpu_cap)¶

Estimates the energy consumed by the CPUs of a performance domain

intem_pd_nr_perf_states(structem_perf_domain*pd)¶

Get the number of performance states of a perf. domain

structem_perf_state*em_perf_state_from_pd(structem_perf_domain*pd)¶

Get the performance states table of perf. domain

intem_dev_update_perf_domain(structdevice*dev,structem_perf_table*new_table)¶

Update runtime EM table for a device

structem_perf_domain*em_pd_get(structdevice*dev)¶

Return the performance domain for a device

structem_perf_domain*em_cpu_get(intcpu)¶

Return the performance domain for a CPU

intem_dev_register_perf_domain(structdevice*dev,unsignedintnr_states,conststructem_data_callback*cb,constcpumask_t*cpus,boolmicrowatts)¶

Register the Energy Model (EM) for a device

intem_dev_register_pd_no_update(structdevice*dev,unsignedintnr_states,conststructem_data_callback*cb,constcpumask_t*cpus,boolmicrowatts)¶

Register a perf domain for a device

voidem_dev_unregister_perf_domain(structdevice*dev)¶

Unregister Energy Model (EM) for a device

intem_dev_update_chip_binning(structdevice*dev)¶

Update Energy Model after the new voltage information is present in the OPPs.

intem_update_performance_limits(structem_perf_domain*pd,unsignedlongfreq_min_khz,unsignedlongfreq_max_khz)¶

Update Energy Model with performance limits information.

3.1 Example driver with EM registration¶

The CPUFreq framework supports dedicated callback for registeringthe EM for a given CPU(s) ‘policy’ object: cpufreq_driver::register_em().That callback has to be implemented properly for a given driver,because the framework would call it at the right time during setup.This section provides a simple example of a CPUFreq driver registering aperformance domain in the Energy Model framework using the (fake) ‘foo’protocol. The driver implements anest_power() function to be provided to theEM framework:

-> drivers/cpufreq/foo_cpufreq.c01    static int est_power(struct device *dev, unsigned long *mW,02                    unsigned long *KHz)03    {04            long freq, power;0506            /* Use the 'foo' protocol to ceil the frequency */07            freq = foo_get_freq_ceil(dev, *KHz);08            if (freq < 0);09                    return freq;1011            /* Estimate the power cost for the dev at the relevant freq. */12            power = foo_estimate_power(dev, freq);13            if (power < 0);14                    return power;1516            /* Return the values to the EM framework */17            *mW = power;18            *KHz = freq;1920            return 0;21    }2223    static void foo_cpufreq_register_em(struct cpufreq_policy *policy)24    {25            struct em_data_callback em_cb = EM_DATA_CB(est_power);26            struct device *cpu_dev;27            int nr_opp;2829            cpu_dev = get_cpu_device(cpumask_first(policy->cpus));3031            /* Find the number of OPPs for this policy */32            nr_opp = foo_get_nr_opp(policy);3334            /* And register the new performance domain */35            em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus,36                                        true);37    }3839    static struct cpufreq_driver foo_cpufreq_driver = {40            .register_em = foo_cpufreq_register_em,41    };

3.2 Example driver with EM modification¶

This section provides a simple example of a thermal driver modifying the EM.The driver implements afoo_thermal_em_update() function. The driver is wokenup periodically to check the temperature and modify the EM data:

-> drivers/soc/example/example_em_mod.c01    static void foo_get_new_em(struct foo_context *ctx)02    {03            struct em_perf_table __rcu *em_table;04            struct em_perf_state *table, *new_table;05            struct device *dev = ctx->dev;06            struct em_perf_domain *pd;07            unsigned long freq;08            int i, ret;0910            pd = em_pd_get(dev);11            if (!pd)12                    return;1314            em_table = em_table_alloc(pd);15            if (!em_table)16                    return;1718            new_table = em_table->state;1920            rcu_read_lock();21            table = em_perf_state_from_pd(pd);22            for (i = 0; i < pd->nr_perf_states; i++) {23                    freq = table[i].frequency;24                    foo_get_power_perf_values(dev, freq, &new_table[i]);25            }26            rcu_read_unlock();2728            /* Calculate 'cost' values for EAS */29            ret = em_dev_compute_costs(dev, new_table, pd->nr_perf_states);30            if (ret) {31                    dev_warn(dev, "EM: compute costs failed %d\n", ret);32                    em_table_free(em_table);33                    return;34            }3536            ret = em_dev_update_perf_domain(dev, em_table);37            if (ret) {38                    dev_warn(dev, "EM: update failed %d\n", ret);39                    em_table_free(em_table);40                    return;41            }4243            /*44             * Since it's one-time-update drop the usage counter.45             * The EM framework will later free the table when needed.46             */47            em_table_free(em_table);48    }4950    /*51     * Function called periodically to check the temperature and52     * update the EM if needed53     */54    static void foo_thermal_em_update(struct foo_context *ctx)55    {56            struct device *dev = ctx->dev;57            int cpu;5859            ctx->temperature = foo_get_temp(dev, ctx);60            if (ctx->temperature < FOO_EM_UPDATE_TEMP_THRESHOLD)61                    return;6263            foo_get_new_em(ctx);64    }