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.