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 "services.hpp"
19 
20 #include <string>
21 
22 namespace phosphor::power::regulators
23 {
24 
25 /**
26  * Voltage regulator sensor type.
27  */
28 enum class SensorType
29 {
30     /**
31      * Output current.
32      */
33     iout,
34 
35     /**
36      * Highest output current.
37      */
38     iout_peak,
39 
40     /**
41      * Lowest output current.
42      */
43     iout_valley,
44 
45     /**
46      * Output power.
47      */
48     pout,
49 
50     /**
51      * Temperature.
52      */
53     temperature,
54 
55     /**
56      * Highest temperature.
57      */
58     temperature_peak,
59 
60     /**
61      * Output voltage.
62      */
63     vout,
64 
65     /**
66      * Highest output voltage.
67      */
68     vout_peak,
69 
70     /**
71      * Lowest output voltage.
72      */
73     vout_valley
74 };
75 
76 /**
77  * @namespace sensors
78  *
79  * Contains utility functions related to voltage regulator sensors.
80  */
81 namespace sensors
82 {
83 
84 /**
85  * Returns the name of the specified SensorType.
86  *
87  * The returned string will exactly match the enumerator name, such as
88  * "temperature_peak".
89  *
90  * @param type sensor type
91  * @return sensor type name
92  */
93 std::string toString(SensorType type)
94 {
95     std::string name{};
96     switch (type)
97     {
98         case SensorType::iout:
99             name = "iout";
100             break;
101         case SensorType::iout_peak:
102             name = "iout_peak";
103             break;
104         case SensorType::iout_valley:
105             name = "iout_valley";
106             break;
107         case SensorType::pout:
108             name = "pout";
109             break;
110         case SensorType::temperature:
111             name = "temperature";
112             break;
113         case SensorType::temperature_peak:
114             name = "temperature_peak";
115             break;
116         case SensorType::vout:
117             name = "vout";
118             break;
119         case SensorType::vout_peak:
120             name = "vout_peak";
121             break;
122         case SensorType::vout_valley:
123             name = "vout_valley";
124             break;
125     }
126     return name;
127 }
128 
129 } // namespace sensors
130 
131 /**
132  * @class Sensors
133  *
134  * Abstract base class for a service that maintains a list of voltage regulator
135  * sensors.
136  *
137  * This service makes the voltage regulator sensors available to other BMC
138  * applications.  For example, the Redfish support obtains sensor data from this
139  * service.
140  *
141  * Each voltage rail in the system may provide multiple types of sensor data,
142  * such as temperature, output voltage, and output current (see SensorType).  A
143  * sensor tracks one of these data types for a voltage rail.
144  *
145  * Voltage regulator sensors are typically read frequently based on a timer.
146  * Reading all the sensors once is called a monitoring cycle.  The application
147  * will loop through all voltage rails, reading all supported sensor types for
148  * each rail.  During a monitoring cycle, the following sensor service methods
149  * should be called in the specified order:
150  * - startCycle() // At the start of a sensor monitoring cycle
151  * - startRail()  // Before reading all the sensors for one rail
152  * - setValue()   // To set the value of one sensor for the current rail
153  * - endRail()    // After reading all the sensors for one rail
154  * - endCycle()   // At the end of a sensor monitoring cycle
155  *
156  * This service can be enabled or disabled.  It is typically enabled when the
157  * system is powered on and voltage regulators begin producing output.  It is
158  * typically disabled when the system is powered off.  It can also be
159  * temporarily disabled if other BMC applications need to communicate with the
160  * voltage regulator devices.  When the service is disabled, the sensors still
161  * exist but are in an inactive state since their values are not being updated.
162  */
163 class Sensors
164 {
165   public:
166     // Specify which compiler-generated methods we want
167     Sensors() = default;
168     Sensors(const Sensors&) = delete;
169     Sensors(Sensors&&) = delete;
170     Sensors& operator=(const Sensors&) = delete;
171     Sensors& operator=(Sensors&&) = delete;
172     virtual ~Sensors() = default;
173 
174     /**
175      * Enable the sensors service.
176      *
177      * While the service is enabled, the sensors that it provides will be in an
178      * active state.  This indicates that their value is being updated
179      * periodically.
180      *
181      * @param services system services
182      */
183     virtual void enable(Services& services) = 0;
184 
185     /**
186      * Notify the sensors service that the current sensor monitoring cycle has
187      * ended.
188      *
189      * @param services system services
190      */
191     virtual void endCycle(Services& services) = 0;
192 
193     /**
194      * Notify the sensors service that sensor monitoring has ended for the
195      * current voltage rail.
196      *
197      * @param errorOccurred specifies whether an error occurred while trying to
198      *                      read all the sensors for the current rail
199      * @param services system services
200      */
201     virtual void endRail(bool errorOccurred, Services& services) = 0;
202 
203     /**
204      * Disable the sensors service.
205      *
206      * While the service is disabled, the sensors that it provides will be in an
207      * inactive state.  This indicates that their value is not being updated.
208      *
209      * @param services system services
210      */
211     virtual void disable(Services& services) = 0;
212 
213     /**
214      * Sets the value of one sensor for the current voltage rail.
215      *
216      * @param type sensor type
217      * @param value sensor value
218      * @param services system services
219      */
220     virtual void setValue(SensorType type, double value,
221                           Services& services) = 0;
222 
223     /**
224      * Notify the sensors service that a sensor monitoring cycle is starting.
225      *
226      * @param services system services
227      */
228     virtual void startCycle(Services& services) = 0;
229 
230     /**
231      * Notify the sensors service that sensor monitoring is starting for the
232      * specified voltage rail.
233      *
234      * Calls to setValue() will update sensors for this rail.
235      *
236      * @param rail unique rail ID
237      * @param deviceInventoryPath D-Bus inventory path of the voltage regulator
238      *                            device that produces the rail
239      * @param chassisInventoryPath D-Bus inventory path of the chassis that
240      *                             contains the voltage regulator device
241      * @param services system services
242      */
243     virtual void startRail(const std::string& rail,
244                            const std::string& deviceInventoryPath,
245                            const std::string& chassisInventoryPath,
246                            Services& services) = 0;
247 };
248 
249 } // namespace phosphor::power::regulators
250