Energy analysis

Introduction

As part of the EAS development efforts, support for CPU energy models and energy probes was added to LISA.

Energy model

The EnergyModel class mimics the energy model used by EAS, and lets us do some energy analysis.

Tip

An EnergyModel instance can be generated from a live target using from_target(), providing this target does have an energy model.

Its most noteworthy use is in our EAS behavioural tests, as it lets us estimate the amount of energy consumed in an execution trace and compare this to an estimated energy-optimal placement.

See also

See EnergyModel for more details.

Energy meters

All energy meters inherit from lisa.energy_meter.EnergyMeter, and most of them use one of devlib’s devlib.instrument under the hood.

See also

See EnergyMeter for more details.

HWMON

The hwmon is a generic Linux kernel subsystem, providing access to hardware monitoring components like temperature or voltage/current sensors.

Arm Energy probe (AEP)

ARM Energy Probes are lightweight power measurement tools for software developers. They can monitor up to three voltage rails simultaneously.

See also

Its related class is AEP.

Equipment

The required equipment is the following:

An ARM Energy Probe
A shunt resistor to be connected between the voltage rail and the probe. The voltage drop on the resistor must be at most 165 mv. Therefore depending on the maximum current required by the load, one can properly select the value of the shunt resistor
Install caiman required libraries:
```
sudo apt-get install libudev-dev
```

Clone, compile and install the caiman tool.

git clone https://github.com/ARM-software/caiman.git
cd caiman/caiman && cmake . && make && cd -
cp caiman/caiman /usr/bin

Baylibre ACME cape

The iiocapture instrument exploits the BayLibre ACME solution for measuring power.

To use this instrument you need the following hardware:

A BeagleBone Black
An ACME Cape
Power probes for the ACME Cape

See also

Its related class is ACME.

Setting up the board

First step is to get an IIO version of the ACME BeagleBone black image. The recommended way of using ACME is to use the pre-built image provided by BayLibre.

If you are using a MicroSD card, please ensure that the card is properly inserted in its slot and to keep pressed the power push-button while connecting the power (via the miniUSB cable). Here is an image of the configuration we usually use:

To change the IP address and avoid a buggy route to a /8 to be added on your host, change the address of the board in /usr/bin/acme-usbgadget-udhcpd:

# Use an address that does not clash with your existing networks
#ifconfig usb0 up 10.65.34.1 netmask 255.255.255.0
ifconfig usb0 up 192.168.50.1 netmask 255.255.255.0

Fix the DHCP server config on the ACME board to advertise a small subnet instead of a whole /8:

#start          10.65.34.20     #default: 192.168.0.20
#end            10.65.34.254    #default: 192.168.0.254

# Advertise a /24 subnet which contains both the
#allocated addresses and the address of the board itself
option  subnet  255.255.255.0
start           192.168.50.20
end             192.168.50.254

Once the board is booted, by default it has its IP address associated with the baylibre-acme.local hostname. To check for the board being visible in your network, you can use this command

avahi-browse -a

which will list all the reachable devices.

If you do not want to use avahi, you can refer to it by the static IP of the ethernet-over-USB interface. That has the added benefit of not using the board of somebody else, since that IP is on the USB interface which can only be accessed from your local machine.

Setting up iio-capture

Install the iio-capture tool required libraries:

If libiio-* is available from the repositories in your apt-get, then run sudo apt-get install libiio-utils libiio-dev
Otherwise, follow the instructions on the libiio wiki on how to build it
Clone, compile and install the iio-capture tool

git clone https://github.com/BayLibre/iio-capture.git
cd iio-capture && make && sudo make install && cd -

You can now verify your installation and check that the probes are correctly detected by the iio daemon running on the BeagleBone with a simple command:

iio_info -n baylibre-acme.local

If you have any issues, for example if iio_info hangs, or iio-capture reports “Unsupported write attribute ‘in_oversampling_ratio’”, try rebooting the ACME by SSH:

# (replace baylibre-acme.local if you changed the hostname)
ssh root@baylibre-acme.local reboot

Monsoon Power Monitor

The Monsoon energy meter allows collecting data from Monsoon Solutions Inc’s Power Monitor.

See also

Its related class is Monsoon.

Setup

This meter depends on the monsoon.py script from AOSP. To set this up, download that script from here and run pip install gflags pyserial.

The Power Monitor acts as a power supply as well as an energy meter. LISA doesn’t currently automate setting this up. You’ll need to manually run these commands:

API

Energy model

Classes for modeling and estimating energy usage of CPU systems

exception lisa.energy_model.EnergyModelCapacityError[source]

Bases: Exception

Used by EnergyModel.get_optimal_placements()

class lisa.energy_model.ActiveState(capacity=None, power=None)[source]

Bases: ActiveState

Represents power and compute capacity at a given frequency

Parameters:

capacity – Relative compute capacity at frequency
power – Power usage at frequency

Create new instance of ActiveState(capacity, power)

static __new__(cls, capacity=None, power=None)[source]: Create new instance of ActiveState(capacity, power)

class lisa.energy_model._CpuTree(cpu, children)[source]

Bases: Loggable

Internal class. Abstract representation of a CPU topology.

Each node contains either a single CPU or a set of child nodes.

Attributes:

cpus: CPUs contained in this node. Includes those of child nodes.
cpu: For convenience, this holds the single CPU contained by leaf nodes. None for non-leaf nodes.

cpu: Test yolo

cpus: This is another thingie

iter_nodes()[source]: Iterate over nodes depth-first, post-order

iter_leaves()[source]: Iterate over leaves

class lisa.energy_model.EnergyModelNode(active_states, idle_states, cpu=None, children=None, name=None)[source]

Bases: _CpuTree

Describes topology and energy data for an EnergyModel.

Represents a CPU topology with energy data. The active and idle state data represents the power usage of just the hardware resources of this topology level, not its children. e.g. If the node represents a cluster, the power numbers should not include power used by the CPU - that power should be included the data of the child nodes.

Exactly one of cpu and children must be given.

Parameters:

active_states – Dict mapping frequencies to ActiveState values. Compute capacity data is optional for non-leaf nodes.
idle_states (dict) – Dict mapping idle state names to power usage values
cpu (tuple(int)) – The CPU this node represents. If provided, this is a leaf node.
children (list(EnergyModelNode)) – Non-empty list of child EnergyModelNode objects
name (str) – Optional human-readable name for this node. Leaf (CPU) nodes have a default name of “cpuN” where N is the cpu number.

property max_capacity: Compute capacity at highest frequency

idle_state_by_idx(idx)[source]: Return the idle state with index idx

class lisa.energy_model.EnergyModelRoot(active_states=None, idle_states=None, cpu=None, children=None, name=None)[source]

Bases: EnergyModelNode

Convenience class for root of an EnergyModelNode tree.

Just like EnergyModelNode except that active_states and idle_states aren’t required.

class lisa.energy_model.PowerDomain(idle_states, cpu=None, children=None)[source]

Bases: _CpuTree

Describes the power domain hierarchy for an EnergyModel.

Power domains are a description of the topological dependencies in hardware for entering idle states. “Composite” states such as cluster-sleep states require a set of CPUs to all be idle before that state can be entered. In that case those CPUs can be grouped into a power domain, and that composite state attached to the power domain. Note that cpuidle is not aware of these dependencies; they are typically handled by the platform firmware.

Exactly one of cpu and children must be given. That is, leaves of the PowerDomain tree always contain exactly one CPU - each CPU is represented as being in a power domain of its own. This represents the assumption that all CPUs have at least one idle state (such as ARM WFI) that they can enter independently of other CPUs.

Parameters:

idle_states (list(str)) – List of names of idle states for this power domain. Does not store power data - these names are used as keys into the idle_states field of EnergyModelNode objects.
cpu (int) – The CPU this node represents. If provided, this is a leaf node.
children (list(PowerDomain)) – Non-empty list of child PowerDomain objects

Attributes:

cpus (tuple(int)): CPUs contained in this node. Includes those of child nodes.

class lisa.energy_model.EnergyModel(root_node, root_power_domain, freq_domains)[source]

Bases: Serializable, Loggable

Represents hierarchical CPU topology with power and capacity data

An energy model consists of

A CPU topology, representing the physical (cache/interconnect) topology of the CPUs. Each node stores the energy usage of that node’s hardware when it is in each active or idle state. They also store a compute capacity at each frequency, but this is only meaningful for leaf nodes (CPUs) and may be None at higher levels. These capacity values are relative; the maximum capacity would usually be 1024, the value of SCHED_CAPACITY_SCALE in the Linux kernel scheduler. Use EnergyModelNodes to describe this.
A power domain topology, representing the hierarchy of areas that can be powered down (idled). The power domains are a single tree. Leaf nodes must contain exactly one CPU and the root node must indirectly contain every CPU. Each power domain has a list (maybe empty) of names of idle states that that domain can enter. Use PowerDomains to describe this.
A set of frequency domains, representing groups of CPUs whose clock frequencies must be equal (probably because they share a clock). The frequency domains must be a partition of the CPUs.

Attributes:

cpu_nodes: List of leaf (CPU) :class`:EnergyModelNode
cpus: List of logical CPU numbers in the system
capacity_scale: The relative computational capacity of the most powerful CPU at its highest available frequency. Utilisation is in the interval [0, capacity_scale].

Parameters:

root_node – Root of EnergyModelNode tree
root_power_domain – Root of PowerDomain tree
freq_domains – Collection of collections of logical CPU numbers representing frequency (clock) domains.

Note

The most signficant shortcomings of the model are:

Voltage domains are assumed to be congruent to frequency domains

Idle state power is assumed to be independent of voltage

Temperature is ignored entirely

cpu_utils: CPU util distributions

Used throughout this module: A cpu_utils is a list u where u[N] is the sum of the frequency-invariant, capacity-invariant utilization of tasks placed on CPU N. That is, the quantity represented by a CPU runqueue’s util_avg in the Linux kernel scheduler’s load-tracking system with EAS features enabled.

This represents a static utilization, assuming that tasks don’t change in size (for example representing a set of fixed periodic RT-App workloads). For workloads that change over time, a series of cpu_utils items would be needed to describe the utilization, with a distinct estimation for each item in the series.

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

property biggest_cpus: The CPUs with the highest compute capacity at their highest frequency

property littlest_cpus: The CPUs with the lowest compute capacity at their highest frequency

property is_heterogeneous: True iff CPUs do not all have the same efficiency and OPP range

property cpu_groups: List of lists of CPUs who share the same active state values

property node_groups: List of lists of CPUs nodes who share the same active state values

get_cpu_capacity(cpu, freq=None)[source]

Convenience method to get the capacity of a CPU at a given frequency

Parameters:

cpu – CPU to get capacity for
freq – Frequency to get the CPU capacity at. Default is max capacity.

guess_idle_states(cpus_active)[source]

Pessimistically guess the idle states that each CPU may enter

If a CPU has any tasks it is estimated that it may only enter its shallowest idle state in between task activations. If all the CPUs within a power domain have no tasks, they will all be judged able to enter that domain’s deepest idle state. If any CPU in a domain has work, no CPUs in that domain are assumed to enter any domain shared state.

e.g. Consider a system with

two power domains PD0 and PD1
4 CPUs, with CPUs [0, 1] in PD0 and CPUs [2, 3] in PD1
4 idle states: “WFI”, “cpu-sleep”, “cluster-sleep-0” and “cluster-sleep-1”, where the “cluster-sleep-*” states domain states, i.e. a CPU can only enter those states when both CPUs in the domain are idle.

Then here are some example inputs and outputs:

# All CPUs idle:
[0, 0, 0, 0] -> ["cluster-sleep-1", "cluster-sleep-1",
                 "cluster-sleep-1", "cluster-sleep-1"]

# All CPUs have work
[1, 1, 1, 1] -> ["WFI","WFI","WFI", "WFI"]

# One power domain active, the other idle
[0, 0, 1, 1] -> ["cluster-sleep-1", "cluster-sleep-1", "WFI","WFI"]

# One CPU active.
# Note that CPU 2 has no work but is assumed to never be able to enter
# any "cluster" state.
[0, 0, 0, 1] -> ["cluster-sleep-1", "cluster-sleep-1",
                 "cpu-sleep","WFI"]

Parameters:: cpus_active – list where bool(cpus_active[N]) is False iff no tasks will run on CPU N.
Returns:: List ret where ret[N] is the name of the estimated idle state that CPU N can enter during idle periods.

guess_freqs(cpu_utils, capacity_margin_pct=0)[source]

Work out CPU frequencies required to execute a workload

Find the lowest possible frequency for each CPU that provides enough capacity to satisfy the utilization, taking into account frequency domains.

Parameters:

cpu_utils – Utilization distribution, see cpu_utils
capacity_margin_pct – Capacity margin before overutilizing a CPU

Returns:

List ret where ret[N] is the frequency that CPU N must run at

estimate_from_cpu_util(cpu_utils, freqs=None, idle_states=None)[source]

Estimate the energy usage of the system under a utilization distribution

Optionally also take freqs; a list of frequencies at which each CPU is assumed to run, and idle_states, the idle states that each CPU can enter between activations. If not provided, they will be estimated assuming an ideal selection system (i.e. perfect cpufreq & cpuidle governors).

Parameters:

cpu_utils – Utilization distribution, see cpu_utils
freqs – List of CPU frequencies. Got from guess_freqs() by default.
idle_states – List of CPU frequencies. Got from guess_idle_states() by default.

Returns:

Dict with power in bogo-Watts (bW), with contributions from each system component keyed with a tuple of the CPUs comprising that component (i.e. :attr:EnergyModelNode.cpus)

{
    (0,)    : 10,
    (1,)    : 10,
    (0, 1)  : 5,
}

This represents CPUs 0 and 1 each using 10bW and their shared resources using 5bW for a total of 25bW.

get_optimal_placements(capacities, capacity_margin_pct=0)[source]

Find the optimal distribution of work for a set of tasks

Find a list of candidates which are estimated to be optimal in terms of power consumption, but that do not result in any CPU becoming over-utilized.

If no such candidates exist, i.e. the system being modeled cannot satisfy the workload’s throughput requirements, an EnergyModelCapacityError is raised. For example, if e was an EnergyModel modeling two CPUs with capacity 1024, this error would be raised by:

e.get_optimal_placements({"t1": 800, "t2": 800, "t3: "800"})

This estimation assumes an ideal system of selecting OPPs and idle states for CPUs.

Note

This is a brute force search taking time exponential wrt. the number of tasks.

Parameters:

capacities – Dict mapping tasks to expected utilization values. These tasks are assumed not to change; they have a single static utilization value. A set of single-phase periodic RT-App tasks is an example of a suitable workload for this model.
capacity_margin_pct – Capacity margin before overutilizing a CPU

Returns:

List of cpu_utils items representing distributions of work under optimal task placements, see cpu_utils. Multiple task placements that result in the same CPU utilizations are considered equivalent.

classmethod probe_target(target)[source]

Check if an EnergyModel can be loaded from the target.

Parameters:: target (devlib.target.Target) – Target to look at.

classmethod from_target(target)[source]

Create an instance of (a subclass of) :class:EnergyModel by reading a target filesystem.

Parameters:: target (devlib.target.Target) – Target object to read filesystem from.
Returns:: A instance of a subclass of EnergyModel.

static from_debugfsEM_target(*args, **kwargs)[source]: See LinuxEnergyModel.from_target()

Attention

Deprecated since version 2.0.

from_debugfsEM_target() is deprecated and will be removed in version 4.0, use lisa.energy_model.LinuxEnergyModel.from_target instead

static from_sd_target(*args, **kwargs)[source]: See LegacyEnergyModel.from_target()

Attention

Deprecated since version 2.0.

from_sd_target() is deprecated and will be removed in version 4.0, use lisa.energy_model.LegacyEnergyModel.from_target instead

estimate_from_trace(trace)[source]

Estimate the energy consumption of the system by looking at a trace

Usese the EAS energy model data, and the idle and DVFS conditions reported in the trace, to estimate the energy usage of the system at every given moment.

Takes into account knowledge of power domains - where cpuidle makes impossible claims about idle states (e.g. a CPU in ‘cluster sleep’ while its cluster siblings are running), the states will be minimised.

The accuracy of this is otherwise totally dependent on the accuracy of the EAS energy model and the kernel’s information. This does not take into account cost of idle state of DVFS transitions, nor any other conditions that are invisible to the kernel. The effect any power decisions that the platform makes independently of the kernel cannot be seen in this data. Examples of this _might_ include firmware thermal management invisibly restricting CPU frequencies, or secure-world software with real-time constraints preventing deep CPU idle states.

Parameters:

trace (lisa.trace.Trace) – The trace

Returns:

A DataFrame with a column for each node in the energy model, labelled with the CPU members of the node joined by ‘-‘s. Shows the energy use by each node at each given moment. If you don’t care about those details, call .sum(axis=1) on the returned DataFrame to get a Series that shows overall estimated power usage over time.

Required trace events:

cpu_frequency or userspace@cpu_frequency_devlib

class lisa.energy_model.LinuxEnergyModel(root_node, root_power_domain, freq_domains)[source]

Bases: EnergyModel

Mainline Linux kernel energy model, available since linux 5.0 .

The energy model information is stored in debugfs.

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

static probe_target(target)[source]

Check if an EnergyModel can be loaded from the target.

Parameters:: target (devlib.target.Target) – Target to look at.

classmethod from_target(target, directory='/sys/kernel/debug/energy_model')[source]

Create an EnergyModel by reading a target filesystem on a device with the new Simplified Energy Model present in debugfs.

Parameters:: target (lisa.target.Target) – Target object to read filesystem from.

This uses the energy_model debugfs used usptream to expose the performance domains, their frequencies and power costs. This feature is upstream as of Linux 5.1. It is also available on Android 4.19 and later.

Wrt. idle states - the EnergyModel constructed won’t be aware of any power data or topological dependencies for entering “cluster” idle states since the simplified model has no such concept.

Note

Initialises only class:ActiveStates for CPUs and clears all other levels.

The recognized debugfs hierarchy pointed at by directory is:

|-- cpu0
|   |-- cpus
|   |-- ps:450000
|   |   |-- cost
|   |   |-- frequency
|   |   `-- power
|   |-- ps:575000
|   |   |-- cost
|   |   |-- frequency
|   |   `-- power
|   `-- ps:850000
|       |-- cost
|       |-- frequency
|       `-- power
`-- cpu1
    |-- cpus
    |-- ps:1100000
    |   |-- cost
    |   |-- frequency
    |   `-- power
    |-- ps:450000
    |   |-- cost
    |   |-- frequency
    |   `-- power
    `-- ps:950000
        |-- cost
        |-- frequency
        `-- power

class lisa.energy_model.LegacyEnergyModel(root_node, root_power_domain, freq_domains)[source]

Bases: EnergyModel

Legacy energy model used on Android kernels prior 4.19.

The energy model information is stored in sysfs and contains detailed information about idle states.

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

static probe_target(target)[source]

Check if an EnergyModel can be loaded from the target.

Parameters:: target (devlib.target.Target) – Target to look at.

classmethod from_target(target, filename='/proc/sys/kernel/sched_domain/cpu{}/domain{}/group{}/energy/{}')[source]

Create an EnergyModel by reading a target filesystem

This uses the sysctl added by EAS patches to exposes the cap_states and idle_states fields for each sched_group. This feature depends on CONFIG_SCHED_DEBUG, and is not upstream in mainline Linux.

The kernel doesn’t have an power domain data, so this method assumes that all CPUs are totally independent wrt. idle states - the EnergyModel constructed won’t be aware of the topological dependencies for entering “cluster” idle states.

Assumes the energy model has two-levels (plus the root) - a level for CPUs and a level for ‘clusters’.

Parameters:: target – Devlib target object to read filesystem from. Must have cpufreq and cpuidle modules enabled.
Returns:: Constructed EnergyModel object based on the parameters reported by the target.

Energy meters

class lisa.energy_meter.EnergyReport(channels, report_file, data_frame)

Bases: tuple

Create new instance of EnergyReport(channels, report_file, data_frame)

__getnewargs__(): Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('channels', 'report_file', 'data_frame')

static __new__(_cls, channels, report_file, data_frame): Create new instance of EnergyReport(channels, report_file, data_frame)

channels: Alias for field number 0

data_frame: Alias for field number 2

report_file: Alias for field number 1

class lisa.energy_meter.EnergyMeter(target, res_dir=None)[source]

Bases: Loggable, Configurable

Abstract Base Class of energy meters.

classmethod from_conf(target, conf, res_dir=None)[source]

Build an instance of EnergyMeter from a configuration object.

Parameters:

target (lisa.target.Target) – Target to use
conf – Configuration object to use
res_dir (str or None) – Result directory to use

abstract name()[source]

abstract sample()[source]: Get a sample from the energy meter

abstract reset()[source]: Reset the energy meter

abstract report()[source]: Get total energy consumption since last reset()

class lisa.energy_meter.HWMonConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class for HWMon.

hwmon-conf: HWMon Energy Meter configuration

channel-map (Mapping): Channels to use.

Example YAML:

# HWMon Energy Meter configuration
hwmon-conf:

    # Channels to use
    # type: Mapping
    channel-map: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

class ChannelMap

Bases: HideExekallID

Channels to use

DEFAULT_SRC = {}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class lisa.energy_meter.HWMon(target, channel_map, res_dir=None)[source]

Bases: EnergyMeter

HWMon energy meter

Parameters:: channel_map (collections.abc.Mapping) – Channels to use

Attention

Deprecated since version 2.0.

HWMon is deprecated and will be removed in version 4.0: LISA energy meters are deprecated, please use devlib instruments or contribute the instrument to devlib

CONF_CLASS: alias of HWMonConf

name = 'hwmon'

sample()[source]: Get a sample from the energy meter

reset()[source]: Reset the energy meter

report(out_dir, out_file='energy.json')[source]: Get total energy consumption since last reset()

INIT_KWARGS_KEY_MAP = {'channel_map': ['channel-map']}

class lisa.energy_meter._DevlibContinuousEnergyMeter(target, res_dir=None)[source]

Bases: EnergyMeter

Common functionality for devlib Instruments in CONTINUOUS mode

reset()[source]: Reset the energy meter

report(out_dir, out_energy='energy.json', out_samples='samples.csv')[source]: Get total energy consumption since last reset()

class lisa.energy_meter.AEPConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class for AEP.

aep-conf: AEP Energy Meter configuration

channel-map (Mapping): Channels to use.

resistor-values (Sequence): Resistor values.

labels (Sequence): List of labels.

device-entry (Sequence): TTY device.

Example YAML:

# AEP Energy Meter configuration
aep-conf:

    # Channels to use
    # type: Mapping
    channel-map: _

    # Resistor values
    # type: Sequence
    resistor-values: _

    # List of labels
    # type: Sequence
    labels: _

    # TTY device
    # type: Sequence
    device-entry: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

class ChannelMap

Bases: HideExekallID

Channels to use

DEFAULT_SRC = {'device-entry': '/dev/ttyACM0'}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class DeviceEntry

Bases: HideExekallID

TTY device

class Labels

Bases: HideExekallID

List of labels

class ResistorValues

Bases: HideExekallID

Resistor values

class lisa.energy_meter.AEP(target, resistor_values, labels=None, device_entry='/dev/ttyACM0', res_dir=None)[source]

Bases: _DevlibContinuousEnergyMeter

Arm Energy Probe energy meter

Parameters:

resistor_values (Sequence) – Resistor values
labels (Sequence) – List of labels
device_entry (Sequence) – TTY device

Attention

Deprecated since version 2.0.

AEP is deprecated and will be removed in version 4.0: LISA energy meters are deprecated, please use devlib instruments or contribute the instrument to devlib

name = 'aep'

CONF_CLASS: alias of AEPConf

INIT_KWARGS_KEY_MAP = {'device_entry': ['device-entry'], 'labels': ['labels'], 'resistor_values': ['resistor-values']}

class lisa.energy_meter.MonsoonConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class for Monsoon.

monsoon-conf: Monsoon Energy Meter configuration

channel-map (Mapping): Channels to use.

monsoon-bin (str): monsoon binary path.

tty-device (str): TTY device to use.

Example YAML:

# Monsoon Energy Meter configuration
monsoon-conf:

    # Channels to use
    # type: Mapping
    channel-map: _

    # Monsoon binary path
    # type: str
    monsoon-bin: _

    # TTY device to use
    # type: str
    tty-device: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

class ChannelMap

Bases: HideExekallID

Channels to use

DEFAULT_SRC = {}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class MonsoonBin

Bases: HideExekallID

monsoon binary path

class TtyDevice

Bases: HideExekallID

TTY device to use

class lisa.energy_meter.Monsoon(target, monsoon_bin=None, tty_device=None, res_dir=None)[source]

Bases: _DevlibContinuousEnergyMeter

Monsoon Solutions energy meter

Parameters:

monsoon_bin (str) – monsoon binary path
tty_device (str) – TTY device to use

Attention

Deprecated since version 2.0.

Monsoon is deprecated and will be removed in version 4.0: LISA energy meters are deprecated, please use devlib instruments or contribute the instrument to devlib

name = 'monsoon'

CONF_CLASS: alias of MonsoonConf

INIT_KWARGS_KEY_MAP = {'monsoon_bin': ['monsoon-bin'], 'tty_device': ['tty-device']}

class lisa.energy_meter.ACMEConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class for ACME.

acme-conf: ACME Energy Meter configuration

channel-map (Mapping): Channels to use.

host (str): Hostname or IP address of the ACME board.

iio-capture-bin (str): path to iio-capture binary.

Example YAML:

# ACME Energy Meter configuration
acme-conf:

    # Channels to use
    # type: Mapping
    channel-map: _

    # Hostname or IP address of the ACME board
    # type: str
    host: _

    # Path to iio-capture binary
    # type: str
    iio-capture-bin: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

class ChannelMap

Bases: HideExekallID

Channels to use

DEFAULT_SRC = {'channel-map': {'CH0': 0}, 'host': 'baylibre-acme.local', 'iio-capture-bin': 'iio-capture'}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class Host

Bases: HideExekallID

Hostname or IP address of the ACME board

class IioCaptureBin

Bases: HideExekallID

path to iio-capture binary

class lisa.energy_meter.ACME(target, channel_map={'CH0': 0}, host='baylibre-acme.local', iio_capture_bin='iio-capture', res_dir=None)[source]

Bases: EnergyMeter

BayLibre’s ACME board based EnergyMeter

Parameters:

channel_map (collections.abc.Mapping) – Channels to use
host (str) – Hostname or IP address of the ACME board
iio_capture_bin (str) – path to iio-capture binary

Attention

Deprecated since version 2.0.

ACME is deprecated and will be removed in version 4.0: LISA energy meters are deprecated, please use devlib instruments or contribute the instrument to devlib

name = 'acme'

CONF_CLASS: alias of ACMEConf

REPORT_DELAY_S = 2.0: iio-capture returns an empty string if killed right after its invocation, so we have to enforce a delay between reset() and report()

sample()[source]: Get a sample from the energy meter

reset()[source]: Reset energy meter and start sampling from channels specified in the target configuration.

report(out_dir, out_energy='energy.json')[source]

Stop iio-capture and collect sampled data.

Parameters:

out_dir (str) – Output directory where to store results
out_file (str) – File name where to save energy data

INIT_KWARGS_KEY_MAP = {'channel_map': ['channel-map'], 'host': ['host'], 'iio_capture_bin': ['iio-capture-bin']}

class lisa.energy_meter.Gem5EnergyMeterConf(conf=None, src='user', add_default_src=True)[source]

Bases: SimpleMultiSrcConf, HideExekallID

Configuration class for Gem5EnergyMeter.

gem5-energy-meter-conf: Gem5 Energy Meter configuration

channel-map (Mapping): Channels to use.

Example YAML:

# Gem5 Energy Meter configuration
gem5-energy-meter-conf:

    # Channels to use
    # type: Mapping
    channel-map: _

Warning

Arbitrary code can be executed while loading an instance from a YAML or Pickle file. To include untrusted data in YAML, use the !untrusted tag along with a string

STRUCTURE = <lisa.conf.TopLevelKeyDesc object>

class ChannelMap

Bases: HideExekallID

Channels to use

DEFAULT_SRC = {}: Source added automatically using add_src() under the name ‘default’ when instances are built.

class lisa.energy_meter.Gem5EnergyMeter(target, channel_map, res_dir=None)[source]

Bases: _DevlibContinuousEnergyMeter

Common functionality for devlib Instruments in CONTINUOUS mode

Attention

Deprecated since version 2.0.

Gem5EnergyMeter is deprecated and will be removed in version 4.0: LISA energy meters are deprecated, please use devlib instruments or contribute the instrument to devlib

name = 'gem5'

CONF_CLASS: alias of Gem5EnergyMeterConf

INIT_KWARGS_KEY_MAP = {'channel_map': ['channel-map']}

reset()[source]: Reset the energy meter