1 /**
2  * Copyright © 2021 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 "../zone.hpp"
19 #include "action.hpp"
20 #include "group.hpp"
21 
22 #include <nlohmann/json.hpp>
23 
24 namespace phosphor::fan::control::json
25 {
26 
27 using json = nlohmann::json;
28 
29 /**
30  * @class MappedFloor - Action to set a fan floor based on ranges of
31  *                      multiple sensor values.
32  * For example, consider the following config:
33  *
34  *    {
35  *    "name": "mapped_floor",
36  *    "key_group": "ambient_temp",
37  *    "fan_floors": [
38  *        {
39  *        "key": 27,
40  *        "floors": [
41  *          {
42  *            "group": "altitude",
43  *            "floors": [
44  *               {
45  *                 "value": 5000,
46  *                 "floor": 4500
47  *               }
48  *            ]
49  *          },
50  *          {
51  *            "group": "power_mode",
52  *            "floors": [
53  *               {
54  *                 "value": "MaximumPerformance",
55  *                 "floor": 5000
56  *               }
57  *            ]
58  *          }
59  *        ]
60  *        }
61  *      ]
62  *    }
63  *
64  * When it runs, it will:
65  *
66  * 1. Evaluate the key_group
67  *   - Find the max D-Bus property value (if numeric) of the member properties
68  *     in this group.
69  *   - Check it against each 'key' value in the fan_floor entries until
70  *     the key_group property value < key value, so:
71  *        max ambient temp < 27.
72  *   - If the above check passes, the rest of that entry will be evaluated
73  *     and then the action will be done.
74  *
75  * 2. Evaluate the group values in each floors array entry for this key value.
76  *   - Find the max D-Bus property value (if numeric) of the member properties
77  *     of this group - in this case 'altitude'.
78  *   - Depending on the data type of that group, compare to the 'value' entry:
79  *     - If numeric, check if the group's value is <= the 'value' one
80  *     - Otherwise, check if it is ==
81  *   - If that passes, save the value from the 'floor' entry and continue to
82  *     the next entry in the floors array, which, if present, would specify
83  *     another group to check.  In this case, 'power_mode'.  Repeat the above
84  *     step.
85  *   - After all the group compares are done, choose the largest floor value
86  *     to set the fan floor to.  If any group check results doesn't end in
87  *     a match being found, then the default floor will be set.
88  *
89  * Cases where the default floor will be set:
90  *  - A table entry can't be found based on a key group's value.
91  *  - A table entry can't be found based on a group's value.
92  *  - A value can't be obtained for the 'key_group' D-Bus property group.
93  *  - A value can't be obtained for any of the 'group' property groups.
94  *  - A value is NaN, as no <, <=, or == checks would succeed.
95  *
96  * Other notes:
97  *  - If a group has multiple members, they must be numeric or else
98  *    the code will throw an exception.
99  *
100  *  - The group inside the floors array can also be a Manager parameter, so that
101  *    this action can operate on a parameter value set by another action.
102  *
103  *    So instead of
104  *            "group": "altitude",
105  *    it can be:
106  *            "parameter": "some_parameter"
107  */
108 
109 class MappedFloor : public ActionBase, public ActionRegister<MappedFloor>
110 {
111   public:
112     /* Name of this action */
113     static constexpr auto name = "mapped_floor";
114 
115     MappedFloor() = delete;
116     MappedFloor(const MappedFloor&) = delete;
117     MappedFloor(MappedFloor&&) = delete;
118     MappedFloor& operator=(const MappedFloor&) = delete;
119     MappedFloor& operator=(MappedFloor&&) = delete;
120     ~MappedFloor() = default;
121 
122     /**
123      * @brief Parse the JSON to set the members
124      *
125      * @param[in] jsonObj - JSON configuration of this action
126      * @param[in] groups - Groups of dbus objects the action uses
127      */
128     MappedFloor(const json& jsonObj, const std::vector<Group>& groups);
129 
130     /**
131      * @brief Run the action.  See description above.
132      *
133      * @param[in] zone - Zone to run the action on
134      */
135     void run(Zone& zone) override;
136 
137   private:
138     /**
139      * @brief Parse and set the key group
140      *
141      * @param[in] jsonObj - JSON object for the action
142      */
143     void setKeyGroup(const json& jsonObj);
144 
145     /**
146      * @brief Parses and sets the floor group data members
147      *
148      * @param[in] jsonObj - JSON object for the action
149      */
150     void setFloorTable(const json& jsonObj);
151 
152     /**
153      * @brief Determines the maximum value of the property specified
154      *        for the group of all members in the group.
155      *
156      * If not numeric, and more than one member, will throw an exception.
157      * Converts numeric values to doubles so they can be compared later.
158      *
159      * If cannot get at least one valid value, returns std::nullopt.
160      *
161      * @param[in] group - The group to get the max value of
162      *
163      * @param[in] manager - The Manager object
164      *
165      * @return optional<PropertyVariantType> - The value, or std::nullopt
166      */
167     std::optional<PropertyVariantType> getMaxGroupValue(const Group& group,
168                                                         const Manager& manager);
169 
170     /**
171      * @brief Returns a pointer to the group object specified
172      *
173      * Throws ActionParseError if no group found
174      *
175      * @param[in] name - The group name
176      *
177      * @return const Group* - Pointer to the group
178      */
179     const Group* getGroup(const std::string& name);
180 
181     /* Key group pointer */
182     const Group* _keyGroup;
183 
184     using FloorEntry = std::tuple<PropertyVariantType, uint64_t>;
185 
186     struct FloorGroup
187     {
188         std::variant<const Group*, std::string> groupOrParameter;
189         std::vector<FloorEntry> floorEntries;
190     };
191 
192     struct FanFloors
193     {
194         PropertyVariantType keyValue;
195         std::vector<FloorGroup> floorGroups;
196     };
197 
198     /* The fan floors action data, loaded from JSON */
199     std::vector<FanFloors> _fanFloors;
200 };
201 
202 } // namespace phosphor::fan::control::json
203