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 "power_sequencer_device.hpp"
19 #include "rail.hpp"
20 #include "services.hpp"
21 
22 #include <map>
23 #include <memory>
24 #include <string>
25 #include <utility>
26 #include <vector>
27 
28 namespace phosphor::power::sequencer
29 {
30 
31 /**
32  * @class StandardDevice
33  *
34  * PowerSequencerDevice sub-class that implements the standard pgood fault
35  * detection algorithm.
36  *
37  * When adding support for a new power sequencer device type, create a sub-class
38  * of StandardDevice if possible.  This will ensure that pgood fault detection
39  * works consistently across device types.
40  */
41 class StandardDevice : public PowerSequencerDevice
42 {
43   public:
44     // Specify which compiler-generated methods we want
45     StandardDevice() = delete;
46     StandardDevice(const StandardDevice&) = delete;
47     StandardDevice(StandardDevice&&) = delete;
48     StandardDevice& operator=(const StandardDevice&) = delete;
49     StandardDevice& operator=(StandardDevice&&) = delete;
50     virtual ~StandardDevice() = default;
51 
52     /**
53      * Constructor.
54      *
55      * @param name device name
56      * @param rails voltage rails that are enabled and monitored by this device
57      */
StandardDevice(const std::string & name,std::vector<std::unique_ptr<Rail>> rails)58     explicit StandardDevice(const std::string& name,
59                             std::vector<std::unique_ptr<Rail>> rails) :
60         name{name}, rails{std::move(rails)}
61     {}
62 
63     /** @copydoc PowerSequencerDevice::getName() */
getName() const64     virtual const std::string& getName() const override
65     {
66         return name;
67     }
68 
69     /** @copydoc PowerSequencerDevice::getRails() */
getRails() const70     virtual const std::vector<std::unique_ptr<Rail>>& getRails() const override
71     {
72         return rails;
73     }
74 
75     /** @copydoc PowerSequencerDevice::findPgoodFault()
76      *
77      * Calls prepareForPgoodFaultDetection() before starting detection.  If a
78      * pgood fault is detected, calls storePgoodFaultDebugData().
79      */
80     virtual std::string findPgoodFault(
81         Services& services, const std::string& powerSupplyError,
82         std::map<std::string, std::string>& additionalData) override;
83 
84   protected:
85     /**
86      * Prepare for pgood fault detection.
87      *
88      * Perform any actions that are necessary to prepare for fault detection.
89      * For example, cache information that is slow to obtain and is used
90      * multiple times during detection.
91      *
92      * Default implementation does nothing.  Override in sub-classes if needed.
93      *
94      * @param services System services like hardware presence and the journal
95      */
96     virtual void
prepareForPgoodFaultDetection(Services & services)97         prepareForPgoodFaultDetection([[maybe_unused]] Services& services)
98     {}
99 
100     /**
101      * Returns the GPIO values that can be read from the device, if possible.
102      *
103      * If the device does not support reading GPIO values or an error occurs, an
104      * empty vector is returned.
105      *
106      * @param services System services like hardware presence and the journal
107      * @return GPIO values, or empty vector if values could not be read
108      */
109     virtual std::vector<int> getGPIOValuesIfPossible(Services& services);
110 
111     /**
112      * Checks whether a pgood fault has occurred on one of the rails being
113      * monitored by this device.
114      *
115      * If a pgood fault was found in a rail, a pointer to the Rail object is
116      * returned.
117      *
118      * Throws an exception if an error occurs while trying to obtain the status
119      * of the rails.
120      *
121      * @param services System services like hardware presence and the journal
122      * @param gpioValues GPIO values obtained from the device (if any)
123      * @param additionalData Additional data to include in the error log if
124      *                       a pgood fault was found
125      * @return pointer to Rail object where fault was found, or nullptr if no
126      *         Rail found
127      */
128     virtual Rail* findRailWithPgoodFault(
129         Services& services, const std::vector<int>& gpioValues,
130         std::map<std::string, std::string>& additionalData);
131 
132     /**
133      * Store pgood fault debug data in the specified additional data map.
134      *
135      * The default implementation stores the device name and then calls
136      * storeGPIOValues().
137      *
138      * Sub-classes should override if needed to store device-specific data.
139      *
140      * This method should NOT throw exceptions.  If debug data cannot be
141      * obtained, the error should be caught and ignored so that pgood error
142      * handling can continue.
143      *
144      * @param services System services like hardware presence and the journal
145      * @param gpioValues GPIO values obtained from the device (if any)
146      * @param additionalData Additional data to include in an error log
147      */
148     virtual void storePgoodFaultDebugData(
149         Services& services, const std::vector<int>& gpioValues,
150         std::map<std::string, std::string>& additionalData);
151 
152     /**
153      * Store GPIO values in the specified additional data map.
154      *
155      * The default implementation stores the values as a simple list of
156      * integers.
157      *
158      * Sub-classes should override if more advanced formatting is needed.  For
159      * example, GPIOs could be stored individually with a name and value, or
160      * related GPIOs could be formatted as a group.
161      *
162      * @param services System services like hardware presence and the journal
163      * @param values GPIO values obtained from the device (if any)
164      * @param additionalData Additional data to include in an error log
165      */
166     virtual void
167         storeGPIOValues(Services& services, const std::vector<int>& values,
168                         std::map<std::string, std::string>& additionalData);
169 
170     /**
171      * Device name.
172      */
173     std::string name{};
174 
175     /**
176      * Voltage rails that are enabled and monitored by this device.
177      */
178     std::vector<std::unique_ptr<Rail>> rails{};
179 };
180 
181 } // namespace phosphor::power::sequencer
182