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