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