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      */
58     explicit StandardDevice(const std::string& name,
59                             std::vector<std::unique_ptr<Rail>> rails) :
60         name{name},
61         rails{std::move(rails)}
62     {}
63 
64     /** @copydoc PowerSequencerDevice::getName() */
65     virtual const std::string& getName() const override
66     {
67         return name;
68     }
69 
70     /** @copydoc PowerSequencerDevice::getRails() */
71     virtual const std::vector<std::unique_ptr<Rail>>& getRails() const override
72     {
73         return rails;
74     }
75 
76     /** @copydoc PowerSequencerDevice::findPgoodFault()
77      *
78      * Calls prepareForPgoodFaultDetection() before starting detection.  If a
79      * pgood fault is detected, calls storePgoodFaultDebugData().
80      */
81     virtual std::string findPgoodFault(
82         Services& services, const std::string& powerSupplyError,
83         std::map<std::string, std::string>& additionalData) override;
84 
85   protected:
86     /**
87      * Prepare for pgood fault detection.
88      *
89      * Perform any actions that are necessary to prepare for fault detection.
90      * For example, cache information that is slow to obtain and is used
91      * multiple times during detection.
92      *
93      * Default implementation does nothing.  Override in sub-classes if needed.
94      *
95      * @param services System services like hardware presence and the journal
96      */
97     virtual void
98         prepareForPgoodFaultDetection([[maybe_unused]] Services& services)
99     {}
100 
101     /**
102      * Returns the GPIO values that can be read from the device, if possible.
103      *
104      * If the device does not support reading GPIO values or an error occurs, an
105      * empty vector is returned.
106      *
107      * @return GPIO values, or empty vector if values could not be read
108      */
109     virtual std::vector<int> getGPIOValuesIfPossible();
110 
111     /**
112      * Store pgood fault debug data in the specified additional data map.
113      *
114      * The default implementation stores the device name and all the GPIO
115      * values.  The GPIO values are stored as a simple list of integers.
116      *
117      * Sub-classes should override if needed to store device-specific data
118      * and/or a formatted representation of the GPIO values.
119      *
120      * This method should NOT throw exceptions.  If debug data cannot be
121      * obtained, the error should be caught and ignored so that pgood error
122      * handling can continue.
123      *
124      * @param services System services like hardware presence and the journal
125      * @param gpioValues GPIO values obtained from the device (if any)
126      * @param additionalData Additional data to include in an error log
127      */
128     virtual void storePgoodFaultDebugData(
129         Services& services, const std::vector<int>& gpioValues,
130         std::map<std::string, std::string>& additionalData);
131 
132     /**
133      * Device name.
134      */
135     std::string name{};
136 
137     /**
138      * Voltage rails that are enabled and monitored by this device.
139      */
140     std::vector<std::unique_ptr<Rail>> rails{};
141 };
142 
143 } // namespace phosphor::power::sequencer
144