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 */
71class 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__
265