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 voltage rails that are enabled and monitored by this device.
56      *
57      * @return voltage rails
58      */
59     virtual const std::vector<std::unique_ptr<Rail>>& getRails() const = 0;
60 
61     /**
62      * Returns the GPIO values that can be read from the device.
63      *
64      * The vector indices correspond to the libgpiod line offsets.  For example,
65      * the element at vector index 0 is the GPIO value at libgpiod line offset
66      * 0.  These offsets may correspond to logical pin IDs, but they are usually
67      * different from the physical pin numbers on the device.  Consult the
68      * device documentation for more information.
69      *
70      * Throws an exception if the values could not be read or the device does
71      * not support GPIO values.
72      *
73      * @return GPIO values
74      */
75     virtual std::vector<int> getGPIOValues() = 0;
76 
77     /**
78      * Returns the value of the PMBus STATUS_WORD command for the specified
79      * PMBus page.
80      *
81      * The returned value is in host-endian order.
82      *
83      * Throws an exception if the value could not be obtained or the device does
84      * not support the STATUS_WORD command.
85      *
86      * @param page PMBus page
87      * @return STATUS_WORD value
88      */
89     virtual uint16_t getStatusWord(uint8_t page) = 0;
90 
91     /**
92      * Returns the value of the PMBus STATUS_VOUT command for the specified
93      * PMBus page.
94      *
95      * Throws an exception if the value could not be obtained or the device does
96      * not support the STATUS_VOUT command.
97      *
98      * @param page PMBus page
99      * @return STATUS_VOUT value
100      */
101     virtual uint8_t getStatusVout(uint8_t page) = 0;
102 
103     /**
104      * Returns the value of the PMBus READ_VOUT command for the specified
105      * PMBus page.
106      *
107      * The returned value is in Volts.
108      *
109      * Throws an exception if the value could not be obtained or the device does
110      * not support the READ_VOUT command.
111      *
112      * @param page PMBus page
113      * @return READ_VOUT value in volts
114      */
115     virtual double getReadVout(uint8_t page) = 0;
116 
117     /**
118      * Returns the value of the PMBus VOUT_UV_FAULT_LIMIT command for the
119      * specified PMBus page.
120      *
121      * The returned value is in Volts.
122      *
123      * Throws an exception if the value could not be obtained or the device does
124      * not support the VOUT_UV_FAULT_LIMIT command.
125      *
126      * @param page PMBus page
127      * @return VOUT_UV_FAULT_LIMIT value in volts
128      */
129     virtual double getVoutUVFaultLimit(uint8_t page) = 0;
130 
131     /**
132      * Checks whether a pgood fault has occurred on one of the rails being
133      * monitored by this device.
134      *
135      * If a pgood fault was found, this method returns a string containing the
136      * error that should be logged.  If no fault was found, an empty string is
137      * returned.
138      *
139      * Throws an exception if an error occurs while trying to obtain the status
140      * of the rails.
141      *
142      * @param services System services like hardware presence and the journal
143      * @param powerSupplyError Power supply error that occurred before the pgood
144      *                         fault.  Set to the empty string if no power
145      *                         supply error occurred.  This error may be the
146      *                         root cause if a pgood fault occurred on a power
147      *                         supply rail monitored by this device.
148      * @param additionalData Additional data to include in the error log if
149      *                       a pgood fault was found
150      * @return error that should be logged if a pgood fault was found, or an
151      *         empty string if no pgood fault was found
152      */
153     virtual std::string
154         findPgoodFault(Services& services, const std::string& powerSupplyError,
155                        std::map<std::string, std::string>& additionalData) = 0;
156 };
157 
158 } // namespace phosphor::power::sequencer
159