1 /** 2 * Copyright © 2024 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 "rail.hpp" 19 #include "services.hpp" 20 21 #include <cstdint> 22 #include <map> 23 #include <string> 24 #include <vector> 25 26 namespace phosphor::power::sequencer 27 { 28 29 /** 30 * @class PowerSequencerDevice 31 * 32 * Abstract base class for a hardware device that performs the following tasks: 33 * - Enables (turns on) the voltage rails in the proper sequence 34 * - Checks the pgood (power good) status of each voltage rail 35 */ 36 class PowerSequencerDevice 37 { 38 public: 39 // Specify which compiler-generated methods we want 40 PowerSequencerDevice() = default; 41 PowerSequencerDevice(const PowerSequencerDevice&) = delete; 42 PowerSequencerDevice(PowerSequencerDevice&&) = delete; 43 PowerSequencerDevice& operator=(const PowerSequencerDevice&) = delete; 44 PowerSequencerDevice& operator=(PowerSequencerDevice&&) = delete; 45 virtual ~PowerSequencerDevice() = default; 46 47 /** 48 * Returns the device name. 49 * 50 * @return device name 51 */ 52 virtual const std::string& getName() const = 0; 53 54 /** 55 * Returns the I2C bus for the device. 56 * 57 * @return I2C bus 58 */ 59 virtual uint8_t getBus() const = 0; 60 61 /** 62 * Returns the I2C address for the device. 63 * 64 * @return I2C address 65 */ 66 virtual uint16_t getAddress() const = 0; 67 68 /** 69 * Returns the name of the GPIO that turns this device on and off. 70 * 71 * @return GPIO name 72 */ 73 virtual const std::string& getPowerControlGPIOName() const = 0; 74 75 /** 76 * Returns the name of the GPIO that reads the power good signal from this 77 * device. 78 * 79 * @return GPIO name 80 */ 81 virtual const std::string& getPowerGoodGPIOName() const = 0; 82 83 /** 84 * Returns the voltage rails that are enabled and monitored by this device. 85 * 86 * @return voltage rails 87 */ 88 virtual const std::vector<std::unique_ptr<Rail>>& getRails() const = 0; 89 90 /** 91 * Returns the GPIO values that can be read from the device. 92 * 93 * The vector indices correspond to the libgpiod line offsets. For example, 94 * the element at vector index 0 is the GPIO value at libgpiod line offset 95 * 0. These offsets may correspond to logical pin IDs, but they are usually 96 * different from the physical pin numbers on the device. Consult the 97 * device documentation for more information. 98 * 99 * Throws an exception if the values could not be read or the device does 100 * not support GPIO values. 101 * 102 * @param services System services like hardware presence and the journal 103 * @return GPIO values 104 */ 105 virtual std::vector<int> getGPIOValues(Services& services) = 0; 106 107 /** 108 * Returns the value of the PMBus STATUS_WORD command for the specified 109 * PMBus page. 110 * 111 * The returned value is in host-endian order. 112 * 113 * Throws an exception if the value could not be obtained or the device does 114 * not support the STATUS_WORD command. 115 * 116 * @param page PMBus page 117 * @return STATUS_WORD value 118 */ 119 virtual uint16_t getStatusWord(uint8_t page) = 0; 120 121 /** 122 * Returns the value of the PMBus STATUS_VOUT command for the specified 123 * PMBus page. 124 * 125 * Throws an exception if the value could not be obtained or the device does 126 * not support the STATUS_VOUT command. 127 * 128 * @param page PMBus page 129 * @return STATUS_VOUT value 130 */ 131 virtual uint8_t getStatusVout(uint8_t page) = 0; 132 133 /** 134 * Returns the value of the PMBus READ_VOUT command for the specified 135 * PMBus page. 136 * 137 * The returned value is in Volts. 138 * 139 * Throws an exception if the value could not be obtained or the device does 140 * not support the READ_VOUT command. 141 * 142 * @param page PMBus page 143 * @return READ_VOUT value in volts 144 */ 145 virtual double getReadVout(uint8_t page) = 0; 146 147 /** 148 * Returns the value of the PMBus VOUT_UV_FAULT_LIMIT command for the 149 * specified PMBus page. 150 * 151 * The returned value is in Volts. 152 * 153 * Throws an exception if the value could not be obtained or the device does 154 * not support the VOUT_UV_FAULT_LIMIT command. 155 * 156 * @param page PMBus page 157 * @return VOUT_UV_FAULT_LIMIT value in volts 158 */ 159 virtual double getVoutUVFaultLimit(uint8_t page) = 0; 160 161 /** 162 * Checks whether a pgood fault has occurred on one of the rails being 163 * monitored by this device. 164 * 165 * If a pgood fault was found, this method returns a string containing the 166 * error that should be logged. If no fault was found, an empty string is 167 * returned. 168 * 169 * Throws an exception if an error occurs while trying to obtain the status 170 * of the rails. 171 * 172 * @param services System services like hardware presence and the journal 173 * @param powerSupplyError Power supply error that occurred before the pgood 174 * fault. Set to the empty string if no power 175 * supply error occurred. This error may be the 176 * root cause if a pgood fault occurred on a power 177 * supply rail monitored by this device. 178 * @param additionalData Additional data to include in the error log if 179 * a pgood fault was found 180 * @return error that should be logged if a pgood fault was found, or an 181 * empty string if no pgood fault was found 182 */ 183 virtual std::string findPgoodFault( 184 Services& services, const std::string& powerSupplyError, 185 std::map<std::string, std::string>& additionalData) = 0; 186 }; 187 188 } // namespace phosphor::power::sequencer 189