blob: 1815680d3fdcc1a013eca74123285e548b1df65e [file] [log] [blame]
Shawn McCarneya2461b32019-10-24 18:53:01 -05001/**
2 * Copyright © 2019 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
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050018#include "configuration.hpp"
Shawn McCarneyafb7fc32019-12-11 19:42:03 -060019#include "i2c_interface.hpp"
Shawn McCarneydb0b8332020-04-06 14:13:04 -050020#include "id_map.hpp"
Shawn McCarney32252592021-09-08 15:29:36 -050021#include "phase_fault_detection.hpp"
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050022#include "presence_detection.hpp"
23#include "rail.hpp"
Bob King23243f82020-07-29 10:38:57 +080024#include "services.hpp"
Shawn McCarneyafb7fc32019-12-11 19:42:03 -060025
26#include <memory>
Shawn McCarneya2461b32019-10-24 18:53:01 -050027#include <string>
Shawn McCarneyafb7fc32019-12-11 19:42:03 -060028#include <utility>
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050029#include <vector>
Shawn McCarneya2461b32019-10-24 18:53:01 -050030
Shawn McCarneyea7385b2019-11-07 12:19:32 -060031namespace phosphor::power::regulators
Shawn McCarneya2461b32019-10-24 18:53:01 -050032{
33
Shawn McCarneyeb7bec42020-04-14 09:38:15 -050034// Forward declarations to avoid circular dependencies
35class Chassis;
36class System;
37
Shawn McCarneya2461b32019-10-24 18:53:01 -050038/**
39 * @class Device
40 *
41 * A hardware device, such as a voltage regulator or I/O expander.
42 */
43class Device
44{
45 public:
46 // Specify which compiler-generated methods we want
47 Device() = delete;
48 Device(const Device&) = delete;
49 Device(Device&&) = delete;
50 Device& operator=(const Device&) = delete;
51 Device& operator=(Device&&) = delete;
52 ~Device() = default;
53
54 /**
55 * Constructor.
56 *
57 * @param id unique device ID
Shawn McCarneyafb7fc32019-12-11 19:42:03 -060058 * @param isRegulator indicates whether this device is a voltage regulator
59 * @param fru Field-Replaceable Unit (FRU) for this device
60 * @param i2cInterface I2C interface to this device
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050061 * @param presenceDetection presence detection for this device, if any
62 * @param configuration configuration changes to apply to this device, if
63 * any
Shawn McCarney32252592021-09-08 15:29:36 -050064 * @param phaseFaultDetection phase fault detection for this device, if any
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050065 * @param rails voltage rails produced by this device, if any
Shawn McCarneya2461b32019-10-24 18:53:01 -050066 */
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050067 explicit Device(
68 const std::string& id, bool isRegulator, const std::string& fru,
69 std::unique_ptr<i2c::I2CInterface> i2cInterface,
70 std::unique_ptr<PresenceDetection> presenceDetection = nullptr,
71 std::unique_ptr<Configuration> configuration = nullptr,
Shawn McCarney32252592021-09-08 15:29:36 -050072 std::unique_ptr<PhaseFaultDetection> phaseFaultDetection = nullptr,
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050073 std::vector<std::unique_ptr<Rail>> rails =
74 std::vector<std::unique_ptr<Rail>>{}) :
Shawn McCarneyafb7fc32019-12-11 19:42:03 -060075 id{id},
Shawn McCarney0b1a0e72020-03-11 18:01:44 -050076 isRegulatorDevice{isRegulator}, fru{fru},
Patrick Williams48781ae2023-05-10 07:50:50 -050077 i2cInterface{std::move(i2cInterface)},
78 presenceDetection{std::move(presenceDetection)},
Shawn McCarney32252592021-09-08 15:29:36 -050079 configuration{std::move(configuration)},
Patrick Williams48781ae2023-05-10 07:50:50 -050080 phaseFaultDetection{std::move(phaseFaultDetection)},
81 rails{std::move(rails)}
Adriana Kobylak0c9a33d2021-09-13 18:05:09 +000082 {}
Shawn McCarneya2461b32019-10-24 18:53:01 -050083
84 /**
Shawn McCarneydb0b8332020-04-06 14:13:04 -050085 * Adds this Device object to the specified IDMap.
86 *
87 * Also adds any Rail objects in this Device to the IDMap.
88 *
89 * @param idMap mapping from IDs to the associated Device/Rail/Rule objects
90 */
91 void addToIDMap(IDMap& idMap);
92
93 /**
Shawn McCarney9bd94d32021-01-25 19:40:42 -060094 * Clear any cached data about hardware devices.
95 */
96 void clearCache();
97
98 /**
Shawn McCarney371e2442021-05-14 14:18:07 -050099 * Clears all error history.
100 *
101 * All data on previously logged errors will be deleted. If errors occur
102 * again in the future they will be logged again.
103 *
104 * This method is normally called when the system is being powered on.
105 */
106 void clearErrorHistory();
107
108 /**
Shawn McCarneyb4d18a42020-06-02 10:27:05 -0500109 * Closes this device.
110 *
111 * Closes any interfaces that are open to this device. Releases any other
112 * operating system resources associated with this device.
Bob Kingd692d6d2020-09-14 13:42:57 +0800113 *
114 * @param services system services like error logging and the journal
Shawn McCarneyb4d18a42020-06-02 10:27:05 -0500115 */
Bob Kingd692d6d2020-09-14 13:42:57 +0800116 void close(Services& services);
Shawn McCarneyb4d18a42020-06-02 10:27:05 -0500117
118 /**
Shawn McCarneyeb7bec42020-04-14 09:38:15 -0500119 * Configure this device.
120 *
121 * Applies the configuration changes that are defined for this device, if
122 * any.
123 *
124 * Also configures the voltage rails produced by this device, if any.
125 *
126 * This method should be called during the boot before regulators are
127 * enabled.
128 *
Bob King23243f82020-07-29 10:38:57 +0800129 * @param services system services like error logging and the journal
Shawn McCarneyeb7bec42020-04-14 09:38:15 -0500130 * @param system system that contains the chassis
131 * @param chassis chassis that contains this device
132 */
Bob King23243f82020-07-29 10:38:57 +0800133 void configure(Services& services, System& system, Chassis& chassis);
Shawn McCarneyeb7bec42020-04-14 09:38:15 -0500134
135 /**
Shawn McCarney1fd0b142021-09-09 10:04:22 -0500136 * Detect redundant phase faults in this device.
137 *
138 * Does nothing if phase fault detection is not defined for this device.
139 *
Shawn McCarney54b3ab92021-09-14 17:28:56 -0500140 * This method should be called repeatedly based on a timer.
Shawn McCarney1fd0b142021-09-09 10:04:22 -0500141 *
142 * @param services system services like error logging and the journal
143 * @param system system that contains the chassis
144 * @param chassis chassis that contains the device
145 */
146 void detectPhaseFaults(Services& services, System& system,
147 Chassis& chassis);
148
149 /**
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500150 * Returns the configuration changes to apply to this device, if any.
Shawn McCarneya2461b32019-10-24 18:53:01 -0500151 *
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500152 * @return Pointer to Configuration object. Will equal nullptr if no
153 * configuration changes are defined for this device.
Shawn McCarneya2461b32019-10-24 18:53:01 -0500154 */
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500155 const std::unique_ptr<Configuration>& getConfiguration() const
Shawn McCarneya2461b32019-10-24 18:53:01 -0500156 {
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500157 return configuration;
Shawn McCarneyafb7fc32019-12-11 19:42:03 -0600158 }
159
160 /**
161 * Returns the Field-Replaceable Unit (FRU) for this device.
162 *
163 * Returns the D-Bus inventory path of the FRU. If the device itself is not
164 * a FRU, returns the FRU that contains the device.
165 *
166 * @return FRU for this device
167 */
168 const std::string& getFRU() const
169 {
170 return fru;
171 }
172
173 /**
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500174 * Returns the I2C interface to this device.
Shawn McCarneyafb7fc32019-12-11 19:42:03 -0600175 *
176 * @return I2C interface to device
177 */
178 i2c::I2CInterface& getI2CInterface()
179 {
180 return *i2cInterface;
181 }
182
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500183 /**
184 * Returns the unique ID of this device.
185 *
186 * @return device ID
187 */
188 const std::string& getID() const
189 {
190 return id;
191 }
192
193 /**
Shawn McCarney32252592021-09-08 15:29:36 -0500194 * Returns the phase fault detection for this device, if any.
195 *
196 * @return Pointer to PhaseFaultDetection object. Will equal nullptr if no
197 * phase fault detection is defined for this device.
198 */
199 const std::unique_ptr<PhaseFaultDetection>& getPhaseFaultDetection() const
200 {
201 return phaseFaultDetection;
202 }
203
204 /**
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500205 * Returns the presence detection for this device, if any.
206 *
207 * @return Pointer to PresenceDetection object. Will equal nullptr if no
208 * presence detection is defined for this device.
209 */
210 const std::unique_ptr<PresenceDetection>& getPresenceDetection() const
211 {
212 return presenceDetection;
213 }
214
215 /**
216 * Returns the voltage rails produced by this device, if any.
217 *
218 * @return voltage rails
219 */
220 const std::vector<std::unique_ptr<Rail>>& getRails() const
221 {
222 return rails;
223 }
224
225 /**
Shawn McCarney48033bf2021-01-27 17:56:49 -0600226 * Returns whether this device is present.
227 *
228 * @return true if device is present, false otherwise
229 */
230 bool isPresent(Services& services, System& system, Chassis& chassis)
231 {
232 if (presenceDetection)
233 {
234 // Execute presence detection to determine if device is present
235 return presenceDetection->execute(services, system, chassis, *this);
236 }
237 else
238 {
239 // No presence detection defined; assume device is present
240 return true;
241 }
242 }
243
244 /**
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500245 * Returns whether this device is a voltage regulator.
246 *
247 * @return true if device is a voltage regulator, false otherwise
248 */
249 bool isRegulator() const
250 {
251 return isRegulatorDevice;
252 }
253
Bob King8e1cd0b2020-07-08 13:30:27 +0800254 /**
255 * Monitors the sensors for the voltage rails produced by this device, if
256 * any.
257 *
Shawn McCarney54b3ab92021-09-14 17:28:56 -0500258 * This method should be called repeatedly based on a timer.
Bob King8e1cd0b2020-07-08 13:30:27 +0800259 *
Bob King8a552922020-08-05 17:02:31 +0800260 * @param services system services like error logging and the journal
Bob King8e1cd0b2020-07-08 13:30:27 +0800261 * @param system system that contains the chassis
262 * @param chassis chassis that contains the device
263 */
Bob King8a552922020-08-05 17:02:31 +0800264 void monitorSensors(Services& services, System& system, Chassis& chassis);
Bob King8e1cd0b2020-07-08 13:30:27 +0800265
Shawn McCarneya2461b32019-10-24 18:53:01 -0500266 private:
267 /**
268 * Unique ID of this device.
269 */
270 const std::string id{};
Shawn McCarneyafb7fc32019-12-11 19:42:03 -0600271
272 /**
273 * Indicates whether this device is a voltage regulator.
274 */
275 const bool isRegulatorDevice{false};
276
277 /**
278 * Field-Replaceable Unit (FRU) for this device.
279 *
280 * Set to the D-Bus inventory path of the FRU. If the device itself is not
281 * a FRU, set to the FRU that contains the device.
282 */
283 const std::string fru{};
284
285 /**
286 * I2C interface to this device.
287 */
288 std::unique_ptr<i2c::I2CInterface> i2cInterface{};
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500289
290 /**
291 * Presence detection for this device, if any. Set to nullptr if no
292 * presence detection is defined for this device.
293 */
294 std::unique_ptr<PresenceDetection> presenceDetection{};
295
296 /**
297 * Configuration changes to apply to this device, if any. Set to nullptr if
298 * no configuration changes are defined for this device.
299 */
300 std::unique_ptr<Configuration> configuration{};
301
302 /**
Shawn McCarney32252592021-09-08 15:29:36 -0500303 * Phase fault detection for this device, if any. Set to nullptr if no
304 * phase fault detection is defined for this device.
305 */
306 std::unique_ptr<PhaseFaultDetection> phaseFaultDetection{};
307
308 /**
Shawn McCarney0b1a0e72020-03-11 18:01:44 -0500309 * Voltage rails produced by this device, if any. Vector is empty if no
310 * voltage rails are defined for this device.
311 */
312 std::vector<std::unique_ptr<Rail>> rails{};
Shawn McCarneya2461b32019-10-24 18:53:01 -0500313};
314
Shawn McCarneyea7385b2019-11-07 12:19:32 -0600315} // namespace phosphor::power::regulators