1 /**
2  * Copyright © 2019 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 "configuration.hpp"
19 #include "i2c_interface.hpp"
20 #include "id_map.hpp"
21 #include "presence_detection.hpp"
22 #include "rail.hpp"
23 
24 #include <memory>
25 #include <string>
26 #include <utility>
27 #include <vector>
28 
29 namespace phosphor::power::regulators
30 {
31 
32 // Forward declarations to avoid circular dependencies
33 class Chassis;
34 class System;
35 
36 /**
37  * @class Device
38  *
39  * A hardware device, such as a voltage regulator or I/O expander.
40  */
41 class Device
42 {
43   public:
44     // Specify which compiler-generated methods we want
45     Device() = delete;
46     Device(const Device&) = delete;
47     Device(Device&&) = delete;
48     Device& operator=(const Device&) = delete;
49     Device& operator=(Device&&) = delete;
50     ~Device() = default;
51 
52     /**
53      * Constructor.
54      *
55      * @param id unique device ID
56      * @param isRegulator indicates whether this device is a voltage regulator
57      * @param fru Field-Replaceable Unit (FRU) for this device
58      * @param i2cInterface I2C interface to this device
59      * @param presenceDetection presence detection for this device, if any
60      * @param configuration configuration changes to apply to this device, if
61      *                      any
62      * @param rails voltage rails produced by this device, if any
63      */
64     explicit Device(
65         const std::string& id, bool isRegulator, const std::string& fru,
66         std::unique_ptr<i2c::I2CInterface> i2cInterface,
67         std::unique_ptr<PresenceDetection> presenceDetection = nullptr,
68         std::unique_ptr<Configuration> configuration = nullptr,
69         std::vector<std::unique_ptr<Rail>> rails =
70             std::vector<std::unique_ptr<Rail>>{}) :
71         id{id},
72         isRegulatorDevice{isRegulator}, fru{fru},
73         i2cInterface{std::move(i2cInterface)}, presenceDetection{std::move(
74                                                    presenceDetection)},
75         configuration{std::move(configuration)}, rails{std::move(rails)}
76     {
77     }
78 
79     /**
80      * Adds this Device object to the specified IDMap.
81      *
82      * Also adds any Rail objects in this Device to the IDMap.
83      *
84      * @param idMap mapping from IDs to the associated Device/Rail/Rule objects
85      */
86     void addToIDMap(IDMap& idMap);
87 
88     /**
89      * Configure this device.
90      *
91      * Applies the configuration changes that are defined for this device, if
92      * any.
93      *
94      * Also configures the voltage rails produced by this device, if any.
95      *
96      * This method should be called during the boot before regulators are
97      * enabled.
98      *
99      * @param system system that contains the chassis
100      * @param chassis chassis that contains this device
101      */
102     void configure(System& system, Chassis& chassis);
103 
104     /**
105      * Returns the configuration changes to apply to this device, if any.
106      *
107      * @return Pointer to Configuration object.  Will equal nullptr if no
108      *         configuration changes are defined for this device.
109      */
110     const std::unique_ptr<Configuration>& getConfiguration() const
111     {
112         return configuration;
113     }
114 
115     /**
116      * Returns the Field-Replaceable Unit (FRU) for this device.
117      *
118      * Returns the D-Bus inventory path of the FRU.  If the device itself is not
119      * a FRU, returns the FRU that contains the device.
120      *
121      * @return FRU for this device
122      */
123     const std::string& getFRU() const
124     {
125         return fru;
126     }
127 
128     /**
129      * Returns the I2C interface to this device.
130      *
131      * @return I2C interface to device
132      */
133     i2c::I2CInterface& getI2CInterface()
134     {
135         return *i2cInterface;
136     }
137 
138     /**
139      * Returns the unique ID of this device.
140      *
141      * @return device ID
142      */
143     const std::string& getID() const
144     {
145         return id;
146     }
147 
148     /**
149      * Returns the presence detection for this device, if any.
150      *
151      * @return Pointer to PresenceDetection object.  Will equal nullptr if no
152      *         presence detection is defined for this device.
153      */
154     const std::unique_ptr<PresenceDetection>& getPresenceDetection() const
155     {
156         return presenceDetection;
157     }
158 
159     /**
160      * Returns the voltage rails produced by this device, if any.
161      *
162      * @return voltage rails
163      */
164     const std::vector<std::unique_ptr<Rail>>& getRails() const
165     {
166         return rails;
167     }
168 
169     /**
170      * Returns whether this device is a voltage regulator.
171      *
172      * @return true if device is a voltage regulator, false otherwise
173      */
174     bool isRegulator() const
175     {
176         return isRegulatorDevice;
177     }
178 
179   private:
180     /**
181      * Unique ID of this device.
182      */
183     const std::string id{};
184 
185     /**
186      * Indicates whether this device is a voltage regulator.
187      */
188     const bool isRegulatorDevice{false};
189 
190     /**
191      * Field-Replaceable Unit (FRU) for this device.
192      *
193      * Set to the D-Bus inventory path of the FRU.  If the device itself is not
194      * a FRU, set to the FRU that contains the device.
195      */
196     const std::string fru{};
197 
198     /**
199      * I2C interface to this device.
200      */
201     std::unique_ptr<i2c::I2CInterface> i2cInterface{};
202 
203     /**
204      * Presence detection for this device, if any.  Set to nullptr if no
205      * presence detection is defined for this device.
206      */
207     std::unique_ptr<PresenceDetection> presenceDetection{};
208 
209     /**
210      * Configuration changes to apply to this device, if any.  Set to nullptr if
211      * no configuration changes are defined for this device.
212      */
213     std::unique_ptr<Configuration> configuration{};
214 
215     /**
216      * Voltage rails produced by this device, if any.  Vector is empty if no
217      * voltage rails are defined for this device.
218      */
219     std::vector<std::unique_ptr<Rail>> rails{};
220 };
221 
222 } // namespace phosphor::power::regulators
223