1 /**
2  * Copyright © 2020 IBM Corporation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #include "config_base.hpp"
19 #include "dbus_zone.hpp"
20 #include "fan.hpp"
21 
22 #include <nlohmann/json.hpp>
23 #include <sdeventplus/event.hpp>
24 #include <sdeventplus/utility/timer.hpp>
25 
26 #include <any>
27 #include <chrono>
28 #include <functional>
29 #include <map>
30 #include <memory>
31 #include <tuple>
32 
33 namespace phosphor::fan::control::json
34 {
35 
36 class Manager;
37 
38 using json = nlohmann::json;
39 
40 /* Dbus event timer */
41 using Timer = sdeventplus::utility::Timer<sdeventplus::ClockId::Monotonic>;
42 
43 /**
44  * @class Zone - Represents a configured fan control zone
45  *
46  * A zone object contains the configured attributes for a zone that groups
47  * a number of fans together to be under the same target control. These
48  * configuration attributes include, but are not limited to, the default ceiling
49  * of the fans within the zone, a default floor, the delay between increases, a
50  * decrease interval, and any profiles(OPTIONAL) the zone should be included in.
51  *
52  * (When no profile for a zone is given, the zone defaults to always exist)
53  *
54  */
55 class Zone : public ConfigBase
56 {
57   public:
58     /* JSON file name for zones */
59     static constexpr auto confFileName = "zones.json";
60 
61     Zone() = delete;
62     Zone(const Zone&) = delete;
63     Zone(Zone&&) = delete;
64     Zone& operator=(const Zone&) = delete;
65     Zone& operator=(Zone&&) = delete;
66     ~Zone() = default;
67 
68     /**
69      * Constructor
70      * Parses and populates a zone from JSON object data
71      *
72      * @param[in] jsonObj - JSON object
73      * @param[in] event - sdeventplus event loop
74      * @param[in] mgr - Manager of this zone
75      */
76     Zone(const json& jsonObj, const sdeventplus::Event& event, Manager* mgr);
77 
78     /**
79      * @brief Get the poweron target
80      *
81      * Poweron target is the target the fans within this zone should be set to
82      * when the system is powered on.
83      *
84      * @return Poweron target of this zone
85      */
86     inline const auto& getPoweronTarget() const
87     {
88         return _poweronTarget;
89     }
90 
91     /**
92      * @brief Get the default ceiling
93      *
94      * Default ceiling is the highest target the fans within this zone is
95      * allowed to increase to. The zone's ceiling defaults to this unless
96      * changed by some configured event.
97      *
98      * @return Default ceiling of this zone
99      */
100     inline const auto& getDefaultCeiling() const
101     {
102         return _defaultCeiling;
103     }
104 
105     /**
106      * @brief Get the default floor
107      *
108      * The default floor is the lowest target the fans within this zone
109      * are allowed to decrease to. The zone's floor defaults to this
110      * unless changed by some configured event.
111      *
112      * @return Default floor
113      */
114     inline const auto& getDefaultFloor() const
115     {
116         return _defaultFloor;
117     }
118 
119     /**
120      * @brief Get the increase delay(OPTIONAL)
121      *
122      * The increase delay is the amount of time(in seconds) increases
123      * to a target are delayed before being made. The default is 0, which
124      * results in immediate increase requests when any events result in
125      * a change to the target.
126      *
127      * It is recommend a value other than 0 is configured, but that inherently
128      * depends on the fan controller and configured increases.
129      *
130      * @return Increase delay(in seconds)
131      */
132     inline const auto& getIncDelay() const
133     {
134         return _incDelay;
135     }
136 
137     /**
138      * @brief Get the decrease interval
139      *
140      * Decreases happen on a set interval when no requests for an increase
141      * in fan targets exists. This is the interval(in seconds) at which the fans
142      * within the zone are decreased if events exist that result in a target
143      * decrease.
144      *
145      * @return Decrease interval(in seconds)
146      */
147     inline const auto& getDecInterval() const
148     {
149         return _decInterval;
150     }
151 
152     /**
153      * @brief Get the current target of the zone
154      *
155      * @return - The current target of the zone
156      */
157     inline const auto& getTarget() const
158     {
159         return _target;
160     }
161 
162     /**
163      * @brief Get the target increase delta
164      *
165      * @return - The current target increase delta
166      */
167     inline auto& getIncDelta() const
168     {
169         return _incDelta;
170     };
171 
172     /**
173      * @brief Get the target decrease delta
174      *
175      * @return - The current target decrease delta
176      */
177     inline auto& getDecDelta() const
178     {
179         return _decDelta;
180     };
181 
182     /**
183      * @brief Get the manager of the zone
184      *
185      * @return - The manager of the zone
186      */
187     inline auto* getManager() const
188     {
189         return _manager;
190     }
191 
192     /**
193      * @brief Enable the zone
194      *
195      * Performs the necessary tasks to enable the zone such as restoring any
196      * dbus property states(if persisted), starting the decrement timer, etc...
197      */
198     void enable();
199 
200     /**
201      * @brief Add a fan object to the zone
202      *
203      * @param[in] fan - Unique pointer to a fan object that will be moved into
204      * the zone
205      *
206      * Adds a fan object to the list of fans that make up the zone by moving the
207      * fan object into the list.
208      */
209     void addFan(std::unique_ptr<Fan> fan);
210 
211     /**
212      * Sets all fans in the zone to the target given when the zone is active
213      *
214      * @param[in] target - Target for fans
215      */
216     void setTarget(uint64_t target);
217 
218     /**
219      * Sets and holds all fans in the zone to the target given or releases a
220      * target hold resulting in the fans being held at the highest remaining
221      * hold target if other hold targets had been requested. When no hold
222      * targets exist, the zone returns to being active.
223      *
224      * @param[in] ident - Unique identifier for a target hold
225      * @param[in] target - Target to hold fans at
226      * @param[in] hold - Whether to hold(true) or release(false) a target hold
227      */
228     void setTargetHold(const std::string& ident, uint64_t target, bool hold);
229 
230     /**
231      * @brief Sets the automatic fan control allowed active state
232      *
233      * @param[in] ident - An identifier that affects the active state
234      * @param[in] isActiveAllow - Active state according to group
235      */
236     void setActiveAllow(const std::string& ident, bool isActiveAllow);
237 
238     /**
239      * @brief Set the floor to the given target and increase target to the floor
240      * when the target is below the floor value when floor changes are allowed.
241      *
242      * @param[in] target - Target to set the floor to
243      */
244     void setFloor(uint64_t target);
245 
246     /**
247      * @brief Set the default floor to the given value
248      *
249      * @param[in] value - Value to set the default floor to
250      */
251     inline void setDefaultFloor(uint64_t value)
252     {
253         _defaultFloor = value;
254     }
255 
256     /**
257      * @brief Sets the floor change allowed state
258      *
259      * @param[in] ident - An identifier that affects floor changes
260      * @param[in] isAllow - Allow state according to the identifier
261      */
262     inline void setFloorChangeAllow(const std::string& ident, bool isAllow)
263     {
264         _floorChange[ident] = isAllow;
265     }
266 
267     /**
268      * @brief Sets the decrease allowed state of a group
269      *
270      * @param[in] ident - An identifier that affects speed decreases
271      * @param[in] isAllow - Allow state according to the identifier
272      */
273     inline void setDecreaseAllow(const std::string& ident, bool isAllow)
274     {
275         _decAllowed[ident] = isAllow;
276     }
277 
278     /**
279      * @brief Calculate the requested target from the given delta and increases
280      * the fans, not going above the ceiling.
281      *
282      * @param[in] targetDelta - The delta to increase the target by
283      */
284     void requestIncrease(uint64_t targetDelta);
285 
286     /**
287      * @brief Callback function for the increase timer that delays
288      * processing of requested target increases while fans are increasing
289      */
290     void incTimerExpired();
291 
292     /**
293      * @brief Calculate the lowest requested decrease target from the given
294      * delta within a decrease interval.
295      *
296      * @param[in] targetDelta - The delta to decrease the target by
297      */
298     void requestDecrease(uint64_t targetDelta);
299 
300     /**
301      * @brief Callback function for the decrease timer that processes any
302      * requested target decreases if allowed
303      */
304     void decTimerExpired();
305 
306     /**
307      * @brief Set the requested target base to be used as the target to base a
308      * new requested target from
309      *
310      * @param[in] targetBase - Base target value to use
311      */
312     inline void setRequestTargetBase(uint64_t targetBase)
313     {
314         _requestTargetBase = targetBase;
315     };
316 
317     /**
318      * @brief Set a property to be persisted
319      *
320      * @param[in] intf - Interface containing property
321      * @param[in] prop - Property to be persisted
322      */
323     void setPersisted(const std::string& intf, const std::string& prop);
324 
325     /**
326      * @brief Is the property persisted
327      *
328      * @param[in] intf - Interface containing property
329      * @param[in] prop - Property to check if persisted
330      *
331      * @return - True if property is to be persisted, false otherwise
332      */
333     bool isPersisted(const std::string& intf, const std::string& prop) const;
334 
335     /**
336      * @brief A handler function to set/update a property on a zone
337      * @details Sets or updates a zone's dbus property to the given value using
338      * the provided base dbus object's set property function
339      *
340      * @param[in] intf - Interface on zone object
341      * @param[in] prop - Property on interface
342      * @param[in] func - Zone dbus object's set property function pointer
343      * @param[in] value - Value to set property to
344      * @param[in] persist - Persist property value or not
345      *
346      * @return Lambda function
347      *     A lambda function to set/update the zone dbus object's property
348      */
349     template <typename T>
350     static auto setProperty(const char* intf, const char* prop,
351                             T (DBusZone::*func)(T), T&& value, bool persist)
352     {
353         return [=, value = std::forward<T>(value)](DBusZone& dbusZone,
354                                                    Zone& zone) {
355             (dbusZone.*func)(value);
356             if (persist)
357             {
358                 zone.setPersisted(intf, prop);
359             }
360         };
361     }
362 
363     /**
364      * @brief A handler function to set/update a zone's dbus property's persist
365      * state
366      * @details Sets or updates a zone's dbus property's persist state where the
367      * value of the property is to be left unchanged
368      *
369      * @param[in] intf - Interface on zone object
370      * @param[in] prop - Property on interface
371      * @param[in] persist - Persist property value or not
372      *
373      * @return Lambda function
374      *     A lambda function to set/update the zone's dbus object's property's
375      * persist state
376      */
377     static auto setPropertyPersist(const char* intf, const char* prop,
378                                    bool persist)
379     {
380         return [=](DBusZone&, Zone& zone) {
381             if (persist)
382             {
383                 zone.setPersisted(intf, prop);
384             }
385         };
386     }
387 
388   private:
389     /* The zone's associated dbus object */
390     std::unique_ptr<DBusZone> _dbusZone;
391 
392     /* The zone's manager */
393     Manager* _manager;
394 
395     /* The zone's poweron target value for fans */
396     uint64_t _poweronTarget;
397 
398     /* The zone's default ceiling value for fans */
399     uint64_t _defaultCeiling;
400 
401     /* The zone's default floor value for fans */
402     uint64_t _defaultFloor;
403 
404     /* Zone's increase delay(in seconds) (OPTIONAL) */
405     std::chrono::seconds _incDelay;
406 
407     /* Zone's decrease interval(in seconds) (OPTIONAL) */
408     std::chrono::seconds _decInterval;
409 
410     /* The floor target to not go below */
411     uint64_t _floor;
412 
413     /* Target for this zone */
414     uint64_t _target;
415 
416     /* Zone increase delta */
417     uint64_t _incDelta;
418 
419     /* Zone decrease delta */
420     uint64_t _decDelta;
421 
422     /* The ceiling target to not go above */
423     uint64_t _ceiling;
424 
425     /* Requested target base */
426     uint64_t _requestTargetBase;
427 
428     /* Map of whether floor changes are allowed by a string identifier */
429     std::map<std::string, bool> _floorChange;
430 
431     /* Map of controlling decreases allowed by a string identifer */
432     std::map<std::string, bool> _decAllowed;
433 
434     /* Map of interfaces to persisted properties the zone hosts*/
435     std::map<std::string, std::vector<std::string>> _propsPersisted;
436 
437     /* Automatic fan control active state */
438     bool _isActive;
439 
440     /* The target increase timer object */
441     Timer _incTimer;
442 
443     /* The target decrease timer object */
444     Timer _decTimer;
445 
446     /* Map of active fan control allowed by a string identifier */
447     std::map<std::string, bool> _active;
448 
449     /* Map of target holds by a string identifier */
450     std::unordered_map<std::string, uint64_t> _holds;
451 
452     /* Interface to property mapping of their associated set property handler
453      * function */
454     static const std::map<
455         std::string,
456         std::map<std::string, std::function<std::function<void(
457                                   DBusZone&, Zone&)>(const json&, bool)>>>
458         _intfPropHandlers;
459 
460     /* List of fans included in this zone */
461     std::vector<std::unique_ptr<Fan>> _fans;
462 
463     /* List of configured interface set property functions */
464     std::vector<std::function<void(DBusZone&, Zone&)>> _propInitFunctions;
465 
466     /**
467      * @brief Parse and set the zone's poweron target value
468      *
469      * @param[in] jsonObj - JSON object for the zone
470      *
471      * Sets the poweron target value for the zone from the JSON configuration
472      * object
473      */
474     void setPowerOnTarget(const json& jsonObj);
475 
476     /**
477      * @brief Parse and set the interfaces served by the zone(OPTIONAL)
478      *
479      * @param[in] jsonObj - JSON object for the zone
480      *
481      * Constructs any zone interface handler functions for interfaces that the
482      * zone serves which contains the interface's property's value and
483      * persistency state (OPTIONAL). A property's "persist" state is defaulted
484      * to not be persisted when not given.
485      */
486     void setInterfaces(const json& jsonObj);
487 
488     /**
489      * @brief Get the request target base if defined, otherwise the the current
490      * target is returned
491      *
492      * @return - The request target base or current target
493      */
494     inline auto getRequestTargetBase() const
495     {
496         return (_requestTargetBase != 0) ? _requestTargetBase : _target;
497     };
498 };
499 
500 /**
501  * Properties of interfaces supported by the zone configuration
502  */
503 namespace zone::property
504 {
505 
506 /**
507  * @brief "Supported" property on the "xyz.openbmc_project.Control.ThermalMode"
508  * interface parser. Also creates the handler function for the Zone dbus object
509  * to initialize the property according to what's parsed from the configuration.
510  *
511  * @param[in] jsonObj - JSON object for the "Supported" property
512  * @param[in] persist - Whether to persist the value or not
513  *
514  * @return Zone dbus object's set property function for the "Supported" property
515  */
516 std::function<void(DBusZone&, Zone&)> supported(const json& jsonObj,
517                                                 bool persist);
518 
519 /**
520  * @brief "Current" property on the "xyz.openbmc_project.Control.ThermalMode"
521  * interface parser. Also creates the handler function for the Zone dbus object
522  * to initialize the property according to what's parsed from the configuration.
523  *
524  * @param[in] jsonObj - JSON object for the "Current" property
525  * @param[in] persist - Whether to persist the value or not
526  *
527  * @return Zone dbus object's set property function for the "Current" property
528  */
529 std::function<void(DBusZone&, Zone&)> current(const json& jsonObj,
530                                               bool persist);
531 
532 } // namespace zone::property
533 
534 } // namespace phosphor::fan::control::json
535