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