src/sim/clock_domain.hh

   1 /*
   2  * Copyright (c) 2013-2014, 2019 ARM Limited
   3  * Copyright (c) 2013 Cornell University
   4  * All rights reserved
   5  *
   6  * The license below extends only to copyright in the software and shall
   7  * not be construed as granting a license to any other intellectual
   8  * property including but not limited to intellectual property relating
   9  * to a hardware implementation of the functionality of the software
  10  * licensed hereunder.  You may use the software subject to the license
  11  * terms below provided that you ensure that this notice is replicated
  12  * unmodified and in its entirety in all distributions of the software,
  13  * modified or unmodified, in source code or in binary form.
  14  *
  15  * Redistribution and use in source and binary forms, with or without
  16  * modification, are permitted provided that the following conditions are
  17  * met: redistributions of source code must retain the above copyright
  18  * notice, this list of conditions and the following disclaimer;
  19  * redistributions in binary form must reproduce the above copyright
  20  * notice, this list of conditions and the following disclaimer in the
  21  * documentation and/or other materials provided with the distribution;
  22  * neither the name of the copyright holders nor the names of its
  23  * contributors may be used to endorse or promote products derived from
  24  * this software without specific prior written permission.
  25  *
  26  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  27  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  28  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  29  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  30  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  31  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  32  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  33  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  34  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  35  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  36  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  37  */
  38
  39 /**
  40  * @file
  41  * ClockDomain declarations.
  42  */
  43
  44 #ifndef __SIM_CLOCK_DOMAIN_HH__
  45 #define __SIM_CLOCK_DOMAIN_HH__
  46
  47 #include <algorithm>
  48
  49 #include "base/statistics.hh"
  50 #include "params/ClockDomain.hh"
  51 #include "params/DerivedClockDomain.hh"
  52 #include "params/SrcClockDomain.hh"
  53 #include "sim/sim_object.hh"
  54
  55 /**
  56  * Forward declaration
  57  */
  58 class DerivedClockDomain;
  59 class VoltageDomain;
  60 class Clocked;
  61
  62 /**
  63  * The ClockDomain provides clock to group of clocked objects bundled
  64  * under the same clock domain. The clock domains, in turn, are
  65  * grouped into voltage domains. The clock domains provide support for
  66  * a hierarchial structure with source and derived domains.
  67  */
  68 class ClockDomain : public SimObject
  69 {
  70   protected:
  71
  72     /**
  73      * Pre-computed clock period in ticks. This is populated by the
  74      * inheriting classes based on how their period is determined.
  75      */
  76     Tick _clockPeriod;
  77
  78     /**
  79      * Voltage domain this clock domain belongs to
  80      */
  81     VoltageDomain *_voltageDomain;
  82
  83     /**
  84      * Pointers to potential derived clock domains so we can propagate
  85      * changes.
  86      */
  87     std::vector<DerivedClockDomain*> children;
  88
  89     /**
  90      * Pointers to members of this clock domain, so that when the clock
  91      * period changes, we can update each member's tick.
  92      */
  93     std::vector<Clocked *> members;
  94
  95   public:
  96
  97     typedef ClockDomainParams Params;
  98     ClockDomain(const Params &p, VoltageDomain *voltage_domain);
  99
 100     /**
 101      * Get the clock period.
 102      *
 103      * @return Clock period in ticks
 104      */
 105     Tick clockPeriod() const { return _clockPeriod; }
 106
 107     /**
 108      * Register a Clocked object with this ClockDomain.
 109      *
 110      * @param Clocked to add as a member
 111      */
 112     void registerWithClockDomain(Clocked *c)
 113     {
 114         assert(c != NULL);
 115         assert(std::find(members.begin(), members.end(), c) == members.end());
 116         members.push_back(c);
 117     }
 118
 119     /**
 120      * Get the voltage domain.
 121      *
 122      * @return Voltage domain this clock domain belongs to
 123      */
 124     inline VoltageDomain *voltageDomain() const { return _voltageDomain; }
 125
 126
 127     /**
 128      * Get the current voltage this clock domain operates at.
 129      *
 130      * @return Voltage applied to the clock domain
 131      */
 132     double voltage() const;
 133
 134     /**
 135      * Add a derived domain.
 136      *
 137      * @param Derived domain to add as a child
 138      */
 139     void addDerivedDomain(DerivedClockDomain *clock_domain)
 140     { children.push_back(clock_domain); }
 141
 142   private:
 143     struct ClockDomainStats : public Stats::Group
 144     {
 145         ClockDomainStats(ClockDomain &cd);
 146
 147         /**
 148          * Stat to report clock period of clock domain
 149          */
 150         Stats::Value clock;
 151     } stats;
 152 };
 153
 154 /**
 155  * The source clock domains provides the notion of a clock domain that is
 156  * connected to a tunable clock source. It maintains the clock period and
 157  * provides methods for setting/getting the clock and  configuration parameters
 158  * for clock domain that handler is going to manage. This includes frequency
 159  * values at various performance levels, domain id, and current performance
 160  * level. Note that a performance level as requested by the software corresponds
 161  * to one of the frequency operational points the domain can operate at.
 162  */
 163 class SrcClockDomain : public ClockDomain
 164 {
 165
 166   public:
 167
 168     typedef SrcClockDomainParams Params;
 169     SrcClockDomain(const Params &p);
 170
 171     /**
 172      * Set new clock value
 173      * @param clock The new clock period in ticks
 174      */
 175     void clockPeriod(Tick clock_period);
 176
 177     // Explicitly import the otherwise hidden clockPeriod
 178     using ClockDomain::clockPeriod;
 179
 180     typedef int32_t DomainID;
 181     static const DomainID emptyDomainID = -1;
 182
 183     /**
 184      * @return the domainID of the domain
 185      */
 186     uint32_t domainID() const { return _domainID; }
 187
 188     typedef uint32_t PerfLevel;
 189     /**
 190      * Checks whether the performance level requested exists in the current
 191      * domain configuration
 192      *
 193      * @param the target performance level of the domain
 194      *
 195      * @return validity status of the given performance level
 196      */
 197     bool validPerfLevel(PerfLevel perf_level) const {
 198         return perf_level < numPerfLevels();
 199     }
 200
 201     /**
 202      * Sets the current performance level of the domain
 203      *
 204      * @param perf_level the target performance level
 205      */
 206     void perfLevel(PerfLevel perf_level);
 207
 208     /**
 209      * @return the current performance level of the domain
 210      */
 211     PerfLevel perfLevel() const { return _perfLevel; }
 212
 213     /**
 214      * Get the number of available performance levels for this clock domain.
 215      *
 216      * @return Number of perf levels configured for this domain.
 217      */
 218     PerfLevel numPerfLevels() const {return freqOpPoints.size();}
 219
 220     /**
 221      * @returns the clock period (expressed in ticks) for the current
 222      * performance level
 223      */
 224     Tick clkPeriodAtPerfLevel() const { return freqOpPoints[perfLevel()]; }
 225
 226     Tick clkPeriodAtPerfLevel(PerfLevel perf_level) const
 227     {
 228         assert(validPerfLevel(perf_level));
 229         return freqOpPoints[perf_level];
 230     }
 231
 232     void startup() override;
 233
 234     void serialize(CheckpointOut &cp) const override;
 235     void unserialize(CheckpointIn &cp) override;
 236
 237   private:
 238     /**
 239      * Inform other components about the changed performance level
 240      */
 241     void signalPerfLevelUpdate();
 242
 243     /**
 244       * List of possible frequency operational points, should be in
 245       * descending order
 246       * An empty list corresponds to default frequency specified for its
 247       * clock domain, overall implying NO DVFS
 248       */
 249     const std::vector<Tick> freqOpPoints;
 250
 251     /**
 252       * Software recognizable id number for the domain, should be unique for
 253       * each domain
 254       */
 255     const uint32_t _domainID;
 256
 257     /**
 258       * Current performance level the domain is set to.
 259       * The performance level corresponds to one selected frequency (and related
 260       * voltage) from the supplied list of frequencies, with perfLevel = 0 being
 261       * the fastest performance state.
 262       */
 263     PerfLevel _perfLevel;
 264 };
 265
 266 /**
 267  * The derived clock domains provides the notion of a clock domain
 268  * that is connected to a parent clock domain that can either be a
 269  * source clock domain or a derived clock domain. It maintains the
 270  * clock divider and provides methods for getting the clock.
 271  */
 272 class DerivedClockDomain: public ClockDomain
 273 {
 274
 275   public:
 276
 277     typedef DerivedClockDomainParams Params;
 278     DerivedClockDomain(const Params &p);
 279
 280     /**
 281      * Called by the parent clock domain to propagate changes. This
 282      * also involves propagating the change further to any children of
 283      * the derived domain itself.
 284      */
 285     void updateClockPeriod();
 286
 287   private:
 288
 289     /**
 290      * Reference to the parent clock domain this clock domain derives
 291      * its clock period from
 292      */
 293     ClockDomain &parent;
 294
 295     /**
 296      * Local clock divider of the domain
 297      */
 298     const uint64_t clockDivider;
 299 };
 300
 301 #endif