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 * Returns the configuration changes to apply to this device, if any. 138 * 139 * @return Pointer to Configuration object. Will equal nullptr if no 140 * configuration changes are defined for this device. 141 */ 142 const std::unique_ptr<Configuration>& getConfiguration() const 143 { 144 return configuration; 145 } 146 147 /** 148 * Returns the Field-Replaceable Unit (FRU) for this device. 149 * 150 * Returns the D-Bus inventory path of the FRU. If the device itself is not 151 * a FRU, returns the FRU that contains the device. 152 * 153 * @return FRU for this device 154 */ 155 const std::string& getFRU() const 156 { 157 return fru; 158 } 159 160 /** 161 * Returns the I2C interface to this device. 162 * 163 * @return I2C interface to device 164 */ 165 i2c::I2CInterface& getI2CInterface() 166 { 167 return *i2cInterface; 168 } 169 170 /** 171 * Returns the unique ID of this device. 172 * 173 * @return device ID 174 */ 175 const std::string& getID() const 176 { 177 return id; 178 } 179 180 /** 181 * Returns the phase fault detection for this device, if any. 182 * 183 * @return Pointer to PhaseFaultDetection object. Will equal nullptr if no 184 * phase fault detection is defined for this device. 185 */ 186 const std::unique_ptr<PhaseFaultDetection>& getPhaseFaultDetection() const 187 { 188 return phaseFaultDetection; 189 } 190 191 /** 192 * Returns the presence detection for this device, if any. 193 * 194 * @return Pointer to PresenceDetection object. Will equal nullptr if no 195 * presence detection is defined for this device. 196 */ 197 const std::unique_ptr<PresenceDetection>& getPresenceDetection() const 198 { 199 return presenceDetection; 200 } 201 202 /** 203 * Returns the voltage rails produced by this device, if any. 204 * 205 * @return voltage rails 206 */ 207 const std::vector<std::unique_ptr<Rail>>& getRails() const 208 { 209 return rails; 210 } 211 212 /** 213 * Returns whether this device is present. 214 * 215 * @return true if device is present, false otherwise 216 */ 217 bool isPresent(Services& services, System& system, Chassis& chassis) 218 { 219 if (presenceDetection) 220 { 221 // Execute presence detection to determine if device is present 222 return presenceDetection->execute(services, system, chassis, *this); 223 } 224 else 225 { 226 // No presence detection defined; assume device is present 227 return true; 228 } 229 } 230 231 /** 232 * Returns whether this device is a voltage regulator. 233 * 234 * @return true if device is a voltage regulator, false otherwise 235 */ 236 bool isRegulator() const 237 { 238 return isRegulatorDevice; 239 } 240 241 /** 242 * Monitors the sensors for the voltage rails produced by this device, if 243 * any. 244 * 245 * This method should be called once per second. 246 * 247 * @param services system services like error logging and the journal 248 * @param system system that contains the chassis 249 * @param chassis chassis that contains the device 250 */ 251 void monitorSensors(Services& services, System& system, Chassis& chassis); 252 253 private: 254 /** 255 * Unique ID of this device. 256 */ 257 const std::string id{}; 258 259 /** 260 * Indicates whether this device is a voltage regulator. 261 */ 262 const bool isRegulatorDevice{false}; 263 264 /** 265 * Field-Replaceable Unit (FRU) for this device. 266 * 267 * Set to the D-Bus inventory path of the FRU. If the device itself is not 268 * a FRU, set to the FRU that contains the device. 269 */ 270 const std::string fru{}; 271 272 /** 273 * I2C interface to this device. 274 */ 275 std::unique_ptr<i2c::I2CInterface> i2cInterface{}; 276 277 /** 278 * Presence detection for this device, if any. Set to nullptr if no 279 * presence detection is defined for this device. 280 */ 281 std::unique_ptr<PresenceDetection> presenceDetection{}; 282 283 /** 284 * Configuration changes to apply to this device, if any. Set to nullptr if 285 * no configuration changes are defined for this device. 286 */ 287 std::unique_ptr<Configuration> configuration{}; 288 289 /** 290 * Phase fault detection for this device, if any. Set to nullptr if no 291 * phase fault detection is defined for this device. 292 */ 293 std::unique_ptr<PhaseFaultDetection> phaseFaultDetection{}; 294 295 /** 296 * Voltage rails produced by this device, if any. Vector is empty if no 297 * voltage rails are defined for this device. 298 */ 299 std::vector<std::unique_ptr<Rail>> rails{}; 300 }; 301 302 } // namespace phosphor::power::regulators 303