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 <string>
23 #include <vector>
24 
25 namespace phosphor::power::sequencer
26 {
27 
28 /**
29  * @class PowerSequencerDevice
30  *
31  * Abstract base class for a hardware device that performs the following tasks:
32  * - Enables (turns on) the voltage rails in the proper sequence
33  * - Checks the pgood (power good) status of each voltage rail
34  */
35 class PowerSequencerDevice
36 {
37   public:
38     // Specify which compiler-generated methods we want
39     PowerSequencerDevice() = default;
40     PowerSequencerDevice(const PowerSequencerDevice&) = delete;
41     PowerSequencerDevice(PowerSequencerDevice&&) = delete;
42     PowerSequencerDevice& operator=(const PowerSequencerDevice&) = delete;
43     PowerSequencerDevice& operator=(PowerSequencerDevice&&) = delete;
44     virtual ~PowerSequencerDevice() = default;
45 
46     /**
47      * Returns the device name.
48      *
49      * @return device name
50      */
51     virtual const std::string& getName() const = 0;
52 
53     /**
54      * Returns the GPIO values that can be read from the device.
55      *
56      * The vector indices correspond to the libgpiod line offsets.  For example,
57      * the element at vector index 0 is the GPIO value at libgpiod line offset
58      * 0.  These offsets may correspond to logical pin IDs, but they are usually
59      * different from the physical pin numbers on the device.  Consult the
60      * device documentation for more information.
61      *
62      * Throws an exception if the values could not be read or the device does
63      * not support GPIO values.
64      *
65      * @return GPIO values
66      */
67     virtual std::vector<int> getGPIOValues() = 0;
68 
69     /**
70      * Returns the value of the PMBus STATUS_WORD command for the specified
71      * PMBus page.
72      *
73      * The returned value is in host-endian order.
74      *
75      * Throws an exception if the value could not be obtained or the device does
76      * not support the STATUS_WORD command.
77      *
78      * @param page PMBus page
79      * @return STATUS_WORD value
80      */
81     virtual uint16_t getStatusWord(uint8_t page) = 0;
82 
83     /**
84      * Returns the value of the PMBus STATUS_VOUT command for the specified
85      * PMBus page.
86      *
87      * Throws an exception if the value could not be obtained or the device does
88      * not support the STATUS_VOUT command.
89      *
90      * @param page PMBus page
91      * @return STATUS_VOUT value
92      */
93     virtual uint8_t getStatusVout(uint8_t page) = 0;
94 
95     /**
96      * Returns the value of the PMBus READ_VOUT command for the specified
97      * PMBus page.
98      *
99      * The returned value is in Volts.
100      *
101      * Throws an exception if the value could not be obtained or the device does
102      * not support the READ_VOUT command.
103      *
104      * @param page PMBus page
105      * @return READ_VOUT value in volts
106      */
107     virtual double getReadVout(uint8_t page) = 0;
108 
109     /**
110      * Returns the value of the PMBus VOUT_UV_FAULT_LIMIT command for the
111      * specified PMBus page.
112      *
113      * The returned value is in Volts.
114      *
115      * Throws an exception if the value could not be obtained or the device does
116      * not support the VOUT_UV_FAULT_LIMIT command.
117      *
118      * @param page PMBus page
119      * @return VOUT_UV_FAULT_LIMIT value in volts
120      */
121     virtual double getVoutUVFaultLimit(uint8_t page) = 0;
122 
123     /**
124      * Returns whether a pgood fault has occurred on one of the rails being
125      * monitored by this device.
126      *
127      * Throws an exception if an error occurs while trying to obtain the status
128      * of the rails.
129      *
130      * @param powerSupplyError Power supply error that occurred before the pgood
131      *                         fault.  Set to the empty string if no power
132      *                         supply error occurred.  This error may be the
133      *                         root cause if a pgood fault occurred on a power
134      *                         supply rail monitored by this device.
135      * @param error Error that should be logged if this method returns true.
136      * @param additionalData Additional data to include in the error log if
137      *                       this method returns true.
138      * @return true if a pgood fault was found on a rail monitored by this
139      *         device, false otherwise
140      */
141     virtual bool
142         hasPgoodFault(const std::string& powerSupplyError, std::string& error,
143                       std::map<std::string, std::string>& additionalData) = 0;
144 };
145 
146 } // namespace phosphor::power::sequencer
147