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     /**
81      * Executes the actions to configure the specified device.
82      *
83      * This method should be called during the boot before regulators are
84      * enabled.
85      *
86      * @param services system services like error logging and the journal
87      * @param system system that contains the chassis
88      * @param chassis chassis that contains the device
89      * @param device device to configure
90      */
91     void execute(Services& services, System& system, Chassis& chassis,
92                  Device& device);
93 
94     /**
95      * Executes the actions to configure the specified rail.
96      *
97      * This method should be called during the boot before regulators are
98      * enabled.
99      *
100      * @param services system services like error logging and the journal
101      * @param system system that contains the chassis
102      * @param chassis chassis that contains the device
103      * @param device device that contains the rail
104      * @param rail rail to configure
105      */
106     void execute(Services& services, System& system, Chassis& chassis,
107                  Device& device, Rail& rail);
108 
109     /**
110      * Returns the actions that configure the device/rail.
111      *
112      * @return actions
113      */
114     const std::vector<std::unique_ptr<Action>>& getActions() const
115     {
116         return actions;
117     }
118 
119     /**
120      * Returns the optional output voltage value.
121      *
122      * @return optional volts value
123      */
124     std::optional<double> getVolts() const
125     {
126         return volts;
127     }
128 
129   private:
130     /**
131      * Executes the actions to configure a device or rail.
132      *
133      * @param services system services like error logging and the journal
134      * @param system system that contains the chassis
135      * @param chassis chassis that contains the device
136      * @param device device to configure or that contains rail to configure
137      * @param deviceOrRailID ID of the device or rail to configure
138      */
139     void execute(Services& services, System& system, Chassis& chassis,
140                  Device& device, const std::string& deviceOrRailID);
141 
142     /**
143      * Optional output voltage value.
144      */
145     const std::optional<double> volts{};
146 
147     /**
148      * Actions that configure the device/rail.
149      */
150     std::vector<std::unique_ptr<Action>> actions{};
151 };
152 
153 } // namespace phosphor::power::regulators
154