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