1/*
2 * Copyright (c) 2015 ARM Limited
3 * All rights reserved
4 *
5 * The license below extends only to copyright in the software and shall
6 * not be construed as granting a license to any other intellectual
7 * property including but not limited to intellectual property relating
8 * to a hardware implementation of the functionality of the software
9 * licensed hereunder.  You may use the software subject to the license
10 * terms below provided that you ensure that this notice is replicated
11 * unmodified and in its entirety in all distributions of the software,
12 * modified or unmodified, in source code or in binary form.
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions are
16 * met: redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer;
18 * redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials provided with the distribution;
21 * neither the name of the copyright holders nor the names of its
22 * contributors may be used to endorse or promote products derived from
23 * this software without specific prior written permission.
24 *
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 *
37 * Authors: David Guillen Fandos
38 */
39
40#ifndef __SIM_THERMAL_MODEL_HH__
41#define __SIM_THERMAL_MODEL_HH__
42
43#include <vector>
44
45#include "params/ThermalCapacitor.hh"
46#include "params/ThermalModel.hh"
47#include "params/ThermalReference.hh"
48#include "params/ThermalResistor.hh"
49#include "sim/clocked_object.hh"
50#include "sim/power/thermal_domain.hh"
51#include "sim/power/thermal_entity.hh"
52#include "sim/power/thermal_node.hh"
53#include "sim/sim_object.hh"
54
55
56/**
57 * A ThermalResistor is used to model a thermal resistance between two
58 * thermal domains. This domains can be either a reference (fixed temp.) or
59 * a heat producer (power source).
60 */
61class ThermalResistor : public SimObject, public ThermalEntity
62{
63  public:
64    typedef ThermalResistorParams Params;
65    ThermalResistor(const Params *p);
66
67    void serialize(CheckpointOut &cp) const override;
68    void unserialize(CheckpointIn &cp) override;
69
70    void setNodes(ThermalNode * n1, ThermalNode * n2) {
71        node1 = n1;
72        node2 = n2;
73    }
74
75    LinearEquation getEquation(ThermalNode * tn, unsigned n,
76                               double step) const override;
77
78  private:
79    /* Resistance value in K/W */
80    double _resistance;
81    /* Nodes connected to the resistor */
82    ThermalNode * node1, * node2;
83};
84
85/**
86 * A ThermalCapacitor is used to model a thermal capacitance between two
87 * thermal domains. This domains can be either a reference (fixed temp.) or
88 * a heat producer (power source).
89 */
90class ThermalCapacitor : public SimObject, public ThermalEntity
91{
92  public:
93    typedef ThermalCapacitorParams Params;
94    ThermalCapacitor(const Params *p);
95
96    void serialize(CheckpointOut &cp) const override;
97    void unserialize(CheckpointIn &cp) override;
98
99    LinearEquation getEquation(ThermalNode * tn, unsigned n,
100                               double step) const override;
101
102    void setNodes(ThermalNode * n1, ThermalNode * n2) {
103        node1 = n1;
104        node2 = n2;
105    }
106
107  private:
108    /* Capacitance value in J/K */
109    double _capacitance;
110    /* Nodes connected to the resistor */
111    ThermalNode * node1, * node2;
112};
113
114/**
115 * A ThermalReference is a thermal domain with fixed temperature.
116 * It's the homologue to the voltage source in a circuit.
117 */
118class ThermalReference : public SimObject, public ThermalEntity
119{
120  public:
121    typedef ThermalReferenceParams Params;
122    ThermalReference(const Params *p);
123
124    void setNode(ThermalNode * n) {
125        node = n;
126    }
127
128    LinearEquation getEquation(ThermalNode * tn, unsigned n,
129                               double step) const override;
130
131    void serialize(CheckpointOut &cp) const override;
132    void unserialize(CheckpointIn &cp) override;
133
134    /* Fixed temperature value in centigrate degrees */
135    double _temperature;
136    /* Nodes connected to the resistor */
137    ThermalNode * node;
138};
139
140
141/**
142 * @sa \ref gem5PowerModel "gem5 Thermal Model"
143 *
144 * A ThermalModel is the element which ties all thermal objects
145 * together and provides the thermal solver to the system.
146 * It is reponsible for updating temperature for all Thermal
147 * Domains over time by reading power from simobjects.
148 */
149class ThermalModel : public ClockedObject
150{
151  public:
152    typedef ThermalModelParams Params;
153    ThermalModel(const Params *p);
154
155    void addDomain(ThermalDomain * d);
156    void addReference(ThermalReference * r);
157    void addCapacitor(ThermalCapacitor * c);
158    void addResistor(ThermalResistor * r);
159
160    void addNode(ThermalNode * n) { nodes.push_back(n); }
161
162    double getTemp() const;
163
164    void startup() override;
165    void doStep();
166
167    void serialize(CheckpointOut &cp) const override;
168    void unserialize(CheckpointIn &cp) override;
169  private:
170
171    /* Keep track of all components used for the thermal model */
172    std::vector <ThermalDomain *> domains;
173    std::vector <ThermalReference *> references;
174    std::vector <ThermalCapacitor *> capacitors;
175    std::vector <ThermalResistor *> resistors;
176
177    std::vector <ThermalEntity *> entities;
178
179    /* Keep a list of the instantiated nodes */
180    std::vector <ThermalNode*> nodes;
181    std::vector <ThermalNode*> eq_nodes;
182
183    /** Stepping event to update the model values */
184    EventFunctionWrapper stepEvent;
185
186    /** Step in seconds for thermal updates */
187    double _step;
188
189};
190
191#endif
192