power: Add support for power models

This patch adds some basic support for power models in gem5.

The power interface is defined so it can interact with thermal
models as well. It implements a simple power evaluator that
can be used for simple power models that express power in the
form of a math expression. These expressions can use stats
within the same SimObject (or down its hierarchy) and some
magic variables such as "temp" for temperature.
In future patches we will extend this functionality to allow
slightly more complex expressions.

The model allows it to be extended to use other kinds of models.

Finally, the thermal model is updated to use the power usage as input.

1 files changed, 128 insertions, 0 deletions

diff --git a/src/doc/power_thermal_model.doxygen b/src/doc/power_thermal_model.doxygen
new file mode 100644
index 000000000..8b636ab23
--- /dev/null
+++ b/src/doc/power_thermal_model.doxygen
@@ -0,0 +1,128 @@
+# Copyright (c) 2016 ARM Limited
+# All rights reserved
+#
+# The license below extends only to copyright in the software and shall
+# not be construed as granting a license to any other intellectual
+# property including but not limited to intellectual property relating
+# to a hardware implementation of the functionality of the software
+# licensed hereunder.  You may use the software subject to the license
+# terms below provided that you ensure that this notice is replicated
+# unmodified and in its entirety in all distributions of the software,
+# modified or unmodified, in source code or in binary form.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met: redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer;
+# redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution;
+# neither the name of the copyright holders nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Author: David Guillen Fandos
+
+/*! \page gem5PowerModel Gem5 Power & Thermal model
+
+  \tableofcontents
+
+  This document gives an overview of the power and thermal modelling
+  infrastructure in Gem5. The purpose is to give a high level view of
+  all the pieces involved and how they interact with each other and
+  the simulator.
+
+  \section gem5_PM_CD Class overview
+
+  Classes involved in the power model are:
+
+    - PowerModel: Represents a power model for a hardware component.
+
+    - PowerModelState: Represents a power model for a hardware component
+      in a certain power state. It is an abstract class that defines an
+      interface that must be implemented for each model.
+
+    - MathExprPowerModel: Simple implementation of PowerModelState that
+      assumes that power can be modeled using a simple power
+
+  Classes involved in the thermal model are:
+
+    - ThermalModel: Contains the system thermal model logic and state.
+      It performs the power query and temperature update. It also enables
+      gem5 to query for temperature (for OS reporting).
+
+    - ThermalDomain: Represents an entity that generates heat. It's
+      essentially a group of SimObjects grouped under a SubSystem component
+      that have its own thermal behaviour.
+
+    - ThermalNode: Represents a node in the thermal circuital equivalent.
+      The node has a temperature and interacts with other nodes through
+      connections (thermal resistors and capacitors).
+
+    - ThermalReference: Temperature reference for the thermal model
+      (essentially a thermal node with a fixed temperature), can be used
+      to model air or any other constant temperature domains.
+
+    - ThermalEntity: A thermal component that connects two thermal nodes
+      and models a thermal impedance between them. This class is just an
+      abstract interface.
+
+    - ThermalResistor: Implements ThermalEntity to model a thermal resistance
+      between the two nodes it connects. Thermal resistances model the
+      capacity of a material to transfer heat (units in K/W).
+
+    - ThermalCapacitor. Implements ThermalEntity to model a thermal
+      capacitance. Thermal capacitors are used to model material's thermal
+      capacitance, this is, the ability to change a certain material
+      temperature (units in J/K).
+
+  \section gem5_thermal Thermal model
+
+  The thermal model works by creating a circuital equivalent of the
+  simulated platform. Each node in the circuit has a temperature (as
+  voltage equivalent) and power flows between nodes (as current in a
+  circuit).
+
+  To build this equivalent temperature model the platform is required
+  to group the power actors (any component that has a power model)
+  under SubSystems and attach ThermalDomains to those subsystems.
+  Other components might also be created (like ThermalReferences) and
+  connected all together by creating thermal entities (capacitors and
+  resistors).
+
+  Last step to conclude the thermal model is to create the ThermalModel
+  instance itself and attach all the instances used to it, so it can
+  properly update them at runtime. Only one thermal model instance is
+  supported right now and it will automatically report temperature when
+  appropriate (ie. platform sensor devices).
+
+  \section gem5_power Power model
+
+  Every ClockedObject has a power model associated. If this power model is
+  non-null power will be calculated at every stats dump (although it might
+  be possible to force power evaluation at any other point, if the power
+  model uses the stats, it is a good idea to keep both events in sync).
+  The definition of a power model is quite vague in the sense that it is
+  as flexible as users want it to be. The only enforced contraints so far
+  is the fact that a power model has several power state models, one for
+  each possible power state for that hardware block. When it comes to compute
+  power consumption the power is just the weighted average of each power model.
+
+  A power state model is essentially an interface that allows us to define two
+  power functions for dynamic and static. As an example implementation a class
+  called MathExprPowerModel has been provided. This implementation allows the
+  user to define a power model as an equation involving several statistics.
+  There's also some automatic (or "magic") variables such as "temp", which
+  reports temperature.