1 /**
2  * Copyright © 2020 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 "action.hpp"
19 #include "services.hpp"
20 
21 #include <memory>
22 #include <optional>
23 #include <string>
24 #include <utility>
25 #include <vector>
26 
27 namespace phosphor::power::regulators
28 {
29 
30 // Forward declarations to avoid circular dependencies
31 class Chassis;
32 class Device;
33 class Rail;
34 class System;
35 
36 /**
37  * @class Configuration
38  *
39  * Configuration changes that should be applied to a device or regulator rail.
40  * These changes usually override hardware default settings.
41  *
42  * The most common configuration change is setting the output voltage for a
43  * regulator rail.  Other examples include modifying pgood thresholds and
44  * overcurrent settings.
45  *
46  * The configuration changes are applied during the boot before regulators are
47  * enabled.
48  *
49  * The configuration changes are applied by executing one or more actions.
50  *
51  * An output voltage value can be specified if necessary.  The value will be
52  * stored in the ActionEnvironment when the actions are executed.  Actions that
53  * require a volts value, such as PMBusWriteVoutCommandAction, can obtain it
54  * from the ActionEnvironment.
55  */
56 class Configuration
57 {
58   public:
59     // Specify which compiler-generated methods we want
60     Configuration() = delete;
61     Configuration(const Configuration&) = delete;
62     Configuration(Configuration&&) = delete;
63     Configuration& operator=(const Configuration&) = delete;
64     Configuration& operator=(Configuration&&) = delete;
65     ~Configuration() = default;
66 
67     /**
68      * Constructor.
69      *
70      * @param volts optional output voltage value
71      * @param actions actions that configure the device/rail
72      */
73     explicit Configuration(std::optional<double> volts,
74                            std::vector<std::unique_ptr<Action>> actions) :
75         volts{volts},
76         actions{std::move(actions)}
77     {}
78 
79     /**
80      * Executes the actions to configure the specified device.
81      *
82      * This method should be called during the boot before regulators are
83      * enabled.
84      *
85      * @param services system services like error logging and the journal
86      * @param system system that contains the chassis
87      * @param chassis chassis that contains the device
88      * @param device device to configure
89      */
90     void execute(Services& services, System& system, Chassis& chassis,
91                  Device& device);
92 
93     /**
94      * Executes the actions to configure the specified rail.
95      *
96      * This method should be called during the boot before regulators are
97      * enabled.
98      *
99      * @param services system services like error logging and the journal
100      * @param system system that contains the chassis
101      * @param chassis chassis that contains the device
102      * @param device device that contains the rail
103      * @param rail rail to configure
104      */
105     void execute(Services& services, System& system, Chassis& chassis,
106                  Device& device, Rail& rail);
107 
108     /**
109      * Returns the actions that configure the device/rail.
110      *
111      * @return actions
112      */
113     const std::vector<std::unique_ptr<Action>>& getActions() const
114     {
115         return actions;
116     }
117 
118     /**
119      * Returns the optional output voltage value.
120      *
121      * @return optional volts value
122      */
123     std::optional<double> getVolts() const
124     {
125         return volts;
126     }
127 
128   private:
129     /**
130      * Executes the actions to configure a device or rail.
131      *
132      * @param services system services like error logging and the journal
133      * @param system system that contains the chassis
134      * @param chassis chassis that contains the device
135      * @param device device to configure or that contains rail to configure
136      * @param deviceOrRailID ID of the device or rail to configure
137      */
138     void execute(Services& services, System& system, Chassis& chassis,
139                  Device& device, const std::string& deviceOrRailID);
140 
141     /**
142      * Optional output voltage value.
143      */
144     const std::optional<double> volts{};
145 
146     /**
147      * Actions that configure the device/rail.
148      */
149     std::vector<std::unique_ptr<Action>> actions{};
150 };
151 
152 } // namespace phosphor::power::regulators
153