1 /** 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 18 #include "configuration.hpp" 19 #include "i2c_interface.hpp" 20 #include "id_map.hpp" 21 #include "phase_fault_detection.hpp" 22 #include "presence_detection.hpp" 23 #include "rail.hpp" 24 #include "services.hpp" 25 26 #include <memory> 27 #include <string> 28 #include <utility> 29 #include <vector> 30 31 namespace phosphor::power::regulators 32 { 33 34 // Forward declarations to avoid circular dependencies 35 class Chassis; 36 class System; 37 38 /** 39 * @class Device 40 * 41 * A hardware device, such as a voltage regulator or I/O expander. 42 */ 43 class 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 58 * @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 61 * @param presenceDetection presence detection for this device, if any 62 * @param configuration configuration changes to apply to this device, if 63 * any 64 * @param phaseFaultDetection phase fault detection for this device, if any 65 * @param rails voltage rails produced by this device, if any 66 */ 67 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, 72 std::unique_ptr<PhaseFaultDetection> phaseFaultDetection = nullptr, 73 std::vector<std::unique_ptr<Rail>> rails = 74 std::vector<std::unique_ptr<Rail>>{}) : 75 id{id}, 76 isRegulatorDevice{isRegulator}, fru{fru}, 77 i2cInterface{std::move(i2cInterface)}, presenceDetection{std::move( 78 presenceDetection)}, 79 configuration{std::move(configuration)}, 80 phaseFaultDetection{std::move(phaseFaultDetection)}, rails{std::move( 81 rails)} 82 { 83 } 84 85 /** 86 * Adds this Device object to the specified IDMap. 87 * 88 * Also adds any Rail objects in this Device to the IDMap. 89 * 90 * @param idMap mapping from IDs to the associated Device/Rail/Rule objects 91 */ 92 void addToIDMap(IDMap& idMap); 93 94 /** 95 * Clear any cached data about hardware devices. 96 */ 97 void clearCache(); 98 99 /** 100 * Clears all error history. 101 * 102 * All data on previously logged errors will be deleted. If errors occur 103 * again in the future they will be logged again. 104 * 105 * This method is normally called when the system is being powered on. 106 */ 107 void clearErrorHistory(); 108 109 /** 110 * Closes this device. 111 * 112 * Closes any interfaces that are open to this device. Releases any other 113 * operating system resources associated with this device. 114 * 115 * @param services system services like error logging and the journal 116 */ 117 void close(Services& services); 118 119 /** 120 * Configure this device. 121 * 122 * Applies the configuration changes that are defined for this device, if 123 * any. 124 * 125 * Also configures the voltage rails produced by this device, if any. 126 * 127 * This method should be called during the boot before regulators are 128 * enabled. 129 * 130 * @param services system services like error logging and the journal 131 * @param system system that contains the chassis 132 * @param chassis chassis that contains this device 133 */ 134 void configure(Services& services, System& system, Chassis& chassis); 135 136 /** 137 * Detect redundant phase faults in this device. 138 * 139 * Does nothing if phase fault detection is not defined for this device. 140 * 141 * This method should be called every 15 seconds. 142 * 143 * @param services system services like error logging and the journal 144 * @param system system that contains the chassis 145 * @param chassis chassis that contains the device 146 */ 147 void detectPhaseFaults(Services& services, System& system, 148 Chassis& chassis); 149 150 /** 151 * Returns the configuration changes to apply to this device, if any. 152 * 153 * @return Pointer to Configuration object. Will equal nullptr if no 154 * configuration changes are defined for this device. 155 */ 156 const std::unique_ptr<Configuration>& getConfiguration() const 157 { 158 return configuration; 159 } 160 161 /** 162 * Returns the Field-Replaceable Unit (FRU) for this device. 163 * 164 * Returns the D-Bus inventory path of the FRU. If the device itself is not 165 * a FRU, returns the FRU that contains the device. 166 * 167 * @return FRU for this device 168 */ 169 const std::string& getFRU() const 170 { 171 return fru; 172 } 173 174 /** 175 * Returns the I2C interface to this device. 176 * 177 * @return I2C interface to device 178 */ 179 i2c::I2CInterface& getI2CInterface() 180 { 181 return *i2cInterface; 182 } 183 184 /** 185 * Returns the unique ID of this device. 186 * 187 * @return device ID 188 */ 189 const std::string& getID() const 190 { 191 return id; 192 } 193 194 /** 195 * Returns the phase fault detection for this device, if any. 196 * 197 * @return Pointer to PhaseFaultDetection object. Will equal nullptr if no 198 * phase fault detection is defined for this device. 199 */ 200 const std::unique_ptr<PhaseFaultDetection>& getPhaseFaultDetection() const 201 { 202 return phaseFaultDetection; 203 } 204 205 /** 206 * Returns the presence detection for this device, if any. 207 * 208 * @return Pointer to PresenceDetection object. Will equal nullptr if no 209 * presence detection is defined for this device. 210 */ 211 const std::unique_ptr<PresenceDetection>& getPresenceDetection() const 212 { 213 return presenceDetection; 214 } 215 216 /** 217 * Returns the voltage rails produced by this device, if any. 218 * 219 * @return voltage rails 220 */ 221 const std::vector<std::unique_ptr<Rail>>& getRails() const 222 { 223 return rails; 224 } 225 226 /** 227 * Returns whether this device is present. 228 * 229 * @return true if device is present, false otherwise 230 */ 231 bool isPresent(Services& services, System& system, Chassis& chassis) 232 { 233 if (presenceDetection) 234 { 235 // Execute presence detection to determine if device is present 236 return presenceDetection->execute(services, system, chassis, *this); 237 } 238 else 239 { 240 // No presence detection defined; assume device is present 241 return true; 242 } 243 } 244 245 /** 246 * Returns whether this device is a voltage regulator. 247 * 248 * @return true if device is a voltage regulator, false otherwise 249 */ 250 bool isRegulator() const 251 { 252 return isRegulatorDevice; 253 } 254 255 /** 256 * Monitors the sensors for the voltage rails produced by this device, if 257 * any. 258 * 259 * This method should be called once per second. 260 * 261 * @param services system services like error logging and the journal 262 * @param system system that contains the chassis 263 * @param chassis chassis that contains the device 264 */ 265 void monitorSensors(Services& services, System& system, Chassis& chassis); 266 267 private: 268 /** 269 * Unique ID of this device. 270 */ 271 const std::string id{}; 272 273 /** 274 * Indicates whether this device is a voltage regulator. 275 */ 276 const bool isRegulatorDevice{false}; 277 278 /** 279 * Field-Replaceable Unit (FRU) for this device. 280 * 281 * Set to the D-Bus inventory path of the FRU. If the device itself is not 282 * a FRU, set to the FRU that contains the device. 283 */ 284 const std::string fru{}; 285 286 /** 287 * I2C interface to this device. 288 */ 289 std::unique_ptr<i2c::I2CInterface> i2cInterface{}; 290 291 /** 292 * Presence detection for this device, if any. Set to nullptr if no 293 * presence detection is defined for this device. 294 */ 295 std::unique_ptr<PresenceDetection> presenceDetection{}; 296 297 /** 298 * Configuration changes to apply to this device, if any. Set to nullptr if 299 * no configuration changes are defined for this device. 300 */ 301 std::unique_ptr<Configuration> configuration{}; 302 303 /** 304 * Phase fault detection for this device, if any. Set to nullptr if no 305 * phase fault detection is defined for this device. 306 */ 307 std::unique_ptr<PhaseFaultDetection> phaseFaultDetection{}; 308 309 /** 310 * Voltage rails produced by this device, if any. Vector is empty if no 311 * voltage rails are defined for this device. 312 */ 313 std::vector<std::unique_ptr<Rail>> rails{}; 314 }; 315 316 } // namespace phosphor::power::regulators 317