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