src/sim/dvfs_handler.hh

   1 /*
   2  * Copyright (c) 2013-2014 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: Vasileios Spiliopoulos
  38  *          Akash Bagdia
  39  *          Stephan Diestelhorst
  40  */
  41
  42 /**
  43  * @file
  44  * DVFSHandler and DomainConfig class declaration used for managing voltage
  45  * and frequency scaling of the various DVFS domains in the system (with each
  46  * domain having their independent domain configuration information)
  47  */
  48
  49
  50 #ifndef __SIM_DVFS_HANDLER_HH__
  51 #define __SIM_DVFS_HANDLER_HH__
  52
  53 #include <vector>
  54
  55 #include "debug/DVFS.hh"
  56 #include "params/DVFSHandler.hh"
  57 #include "sim/clock_domain.hh"
  58 #include "sim/eventq.hh"
  59 #include "sim/sim_object.hh"
  60
  61 /**
  62  * DVFS Handler class, maintains a list of all the domains it can handle.
  63  * Each entry of that list is an object of the DomainConfig class, and the
  64  * handler uses the methods provided by that class to get access to the
  65  * configuration of each domain. The handler is responsible for setting/getting
  66  * clock periods and voltages from clock/voltage domains.
  67  * The handler acts the bridge between software configurable information
  68  * for each domain as provided to the controller and the hardware
  69  * implementation details for those domains.
  70  */
  71 class DVFSHandler : public SimObject
  72 {
  73   public:
  74     typedef DVFSHandlerParams Params;
  75     DVFSHandler(const Params *p);
  76
  77     typedef SrcClockDomain::DomainID DomainID;
  78     typedef SrcClockDomain::PerfLevel PerfLevel;
  79
  80     /**
  81      * Get the number of domains assigned to this DVFS handler.
  82      * @return Number of domains
  83      */
  84     uint32_t numDomains() const { return domainIDList.size(); }
  85
  86     /**
  87      * Get the n-th domain ID, from the domains managed by this handler.
  88      * @return Domain ID
  89      */
  90     DomainID domainID(uint32_t index) const;
  91
  92     /**
  93      * Check whether a domain ID is known to the handler or not.
  94      * @param domain_id Domain ID to check
  95      * @return Domain ID known to handler?
  96      */
  97     bool validDomainID(DomainID domain_id) const;
  98
  99     /**
 100      * Get transition latency to switch between performance levels.
 101      * @return Transition latency
 102      */
 103     Tick transLatency() const { return _transLatency; }
 104
 105     /**
 106      * Set a new performance level for the specified domain.  The actual update
 107      * will be delayed by transLatency().
 108      *
 109      * @param domain_id Software visible ID of the domain to be configured
 110      * @param perf_level Requested performance level (0 - fast, >0 slower)
 111      * @return status whether the setting was successful
 112      */
 113     bool perfLevel(DomainID domain_id, PerfLevel perf_level);
 114
 115     /**
 116      * Get the current performance level of a domain.  While a change request is
 117      * in-flight, will return the current (i.e. old, unmodified) value.
 118      *
 119      * @param domain_id Domain ID to query
 120      * @return Current performance level of the specified domain
 121      */
 122     PerfLevel perfLevel(DomainID domain_id) const {
 123          assert(isEnabled());
 124          return findDomain(domain_id)->perfLevel();
 125     }
 126
 127     /**
 128      * Read the clock period of the specified domain at the specified
 129      * performance level.
 130      * @param domain_id Domain ID to query
 131      * @param perf_level Performance level of interest
 132      * @return Clock period in ticks for the requested performance level of
 133      * the respective domain
 134      */
 135     Tick clkPeriodAtPerfLevel(DomainID domain_id, PerfLevel perf_level) const
 136     {
 137         SrcClockDomain *d = findDomain(domain_id);
 138         assert(d);
 139         PerfLevel n = d->numPerfLevels();
 140         if (perf_level < n)
 141             return d->clkPeriodAtPerfLevel(perf_level);
 142
 143         warn("DVFSHandler %s reads illegal frequency level %u from "\
 144              "SrcClockDomain %s. Returning 0\n", name(), perf_level, d->name());
 145         return Tick(0);
 146     }
 147
 148     /**
 149      * Read the voltage of the specified domain at the specified
 150      * performance level.
 151      * @param domain_id Domain ID to query
 152      * @param perf_level Performance level of interest
 153      * @return Voltage for the requested performance level of the respective
 154      * domain
 155      */
 156     double voltageAtPerfLevel(DomainID domain_id, PerfLevel perf_level) const;
 157
 158     /**
 159      * Get the total number of available performance levels.
 160      *
 161      * @param domain_id Domain ID to query
 162      * @return Number of performance levels that where configured for the
 163      * respective domain
 164      */
 165     PerfLevel numPerfLevels(PerfLevel domain_id) const
 166     {
 167         return findDomain(domain_id)->numPerfLevels();
 168     }
 169
 170     /**
 171      * Check enable status of the DVFS handler, when the handler is disabled, no
 172      * request should be sent to the handler.
 173      * @return True, if the handler is enabled
 174      */
 175     bool isEnabled() const { return enableHandler; }
 176
 177     void serialize(CheckpointOut &cp) const override;
 178     void unserialize(CheckpointIn &cp) override;
 179
 180   private:
 181     typedef std::map<DomainID, SrcClockDomain*> Domains;
 182     Domains domains;
 183
 184     /**
 185       * List of IDs avaiable in the domain list
 186       */
 187     std::vector<DomainID> domainIDList;
 188
 189     /**
 190       * Clock domain of the system the handler is instantiated.
 191       */
 192     SrcClockDomain* sysClkDomain;
 193
 194     /**
 195      * Search for a domain based on the domain ID.
 196      *
 197      * @param domain_id Domain ID to search for
 198      * @return Pointer to the source clock domain with matching ID.
 199      */
 200     SrcClockDomain *findDomain(DomainID domain_id) const {
 201         auto it = domains.find(domain_id);
 202         panic_if(it == domains.end(),
 203                  "DVFS: Could not find a domain for ID %d.\n",domain_id );
 204         return domains.find(domain_id)->second;
 205     }
 206
 207     /**
 208      * Disabling the DVFS handler ensures that all the DVFS migration requests
 209      * are ignored. Domains remain at their default frequency and voltage.
 210      */
 211     bool enableHandler;
 212
 213
 214     /**
 215      * This corresponds to the maximum transition latency associated with the
 216      * hardware transitioning from a particular performance level to the other
 217      */
 218     const Tick _transLatency;
 219
 220
 221
 222     /**
 223      * Update performance level event, encapsulates all the required information
 224      * for a future call to change a domain's performance level.
 225      */
 226     struct UpdateEvent : public Event {
 227         UpdateEvent() : Event(DVFS_Update_Pri), domainIDToSet(0),
 228                         perfLevelToSet(0) {}
 229
 230         /**
 231          * Static pointer to the single DVFS hander for all the update events
 232          */
 233         static DVFSHandler *dvfsHandler;
 234
 235         /**
 236          * ID of the domain that will be changed by the in-flight event
 237          */
 238         DomainID domainIDToSet;
 239
 240         /**
 241          * Target performance level of the in-flight event
 242          */
 243         PerfLevel perfLevelToSet;
 244
 245         /**
 246          * Updates the performance level by modifying the clock and the voltage
 247          * of the associated clocked objects.  Gets information from
 248          * domainIDToSet and perfLevelToSet for easier calling through an
 249          * event.
 250          */
 251         void updatePerfLevel();
 252
 253         void process() { updatePerfLevel(); }
 254     };
 255
 256     typedef std::map<DomainID, UpdateEvent> UpdatePerfLevelEvents;
 257     /**
 258      * Map from domain IDs -> perf level update events, records in-flight change
 259      * requests per domain ID.
 260      */
 261     UpdatePerfLevelEvents updatePerfLevelEvents;
 262 };
 263
 264 #endif // __SIM_DVFS_HANDLER_HH__