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 "sensor_monitoring.hpp"
20 
21 #include <memory>
22 #include <string>
23 #include <utility>
24 
25 namespace phosphor::power::regulators
26 {
27 
28 // Forward declarations to avoid circular dependencies
29 class Chassis;
30 class Device;
31 class System;
32 
33 /**
34  * @class Rail
35  *
36  * A voltage rail produced by a voltage regulator.
37  *
38  * Voltage regulators produce one or more rails.  Each rail typically provides a
39  * different output voltage level, such as 1.1V.
40  */
41 class Rail
42 {
43   public:
44     // Specify which compiler-generated methods we want
45     Rail() = delete;
46     Rail(const Rail&) = delete;
47     Rail(Rail&&) = delete;
48     Rail& operator=(const Rail&) = delete;
49     Rail& operator=(Rail&&) = delete;
50     ~Rail() = default;
51 
52     /**
53      * Constructor.
54      *
55      * @param id unique rail ID
56      * @param configuration configuration changes to apply to this rail, if any
57      * @param sensorMonitoring sensor monitoring for this rail, if any
58      */
59     explicit Rail(
60         const std::string& id,
61         std::unique_ptr<Configuration> configuration = nullptr,
62         std::unique_ptr<SensorMonitoring> sensorMonitoring = nullptr) :
63         id{id},
64         configuration{std::move(configuration)}, sensorMonitoring{std::move(
65                                                      sensorMonitoring)}
66     {
67     }
68 
69     /**
70      * Configure this rail.
71      *
72      * Applies the configuration changes that are defined for this rail, if any.
73      *
74      * This method should be called during the boot before regulators are
75      * enabled.
76      *
77      * @param system system that contains the chassis
78      * @param chassis chassis that contains the device
79      * @param device device that contains this rail
80      */
81     void configure(System& system, Chassis& chassis, Device& device);
82 
83     /**
84      * Returns the configuration changes to apply to this rail, if any.
85      *
86      * @return Pointer to Configuration object.  Will equal nullptr if no
87      *         configuration changes are defined for this rail.
88      */
89     const std::unique_ptr<Configuration>& getConfiguration() const
90     {
91         return configuration;
92     }
93 
94     /**
95      * Returns the unique ID of this rail.
96      *
97      * @return rail ID
98      */
99     const std::string& getID() const
100     {
101         return id;
102     }
103 
104     /**
105      * Monitor the sensors for this rail.
106      *
107      * Sensor monitoring is optional.  If sensor monitoring is defined for this
108      * rail, the sensor values are read.
109      *
110      * This method should be called once per second.
111      *
112      * @param system system that contains the chassis
113      * @param chassis chassis that contains the device
114      * @param device device that contains this rail
115      */
116     void monitorSensors(System& system, Chassis& chassis, Device& device);
117 
118     /**
119      * Returns the sensor monitoring for this rail, if any.
120      *
121      * @return Pointer to SensorMonitoring object.  Will equal nullptr if no
122      *         sensor monitoring is defined for this rail.
123      */
124     const std::unique_ptr<SensorMonitoring>& getSensorMonitoring() const
125     {
126         return sensorMonitoring;
127     }
128 
129   private:
130     /**
131      * Unique ID of this rail.
132      */
133     const std::string id{};
134 
135     /**
136      * Configuration changes to apply to this rail, if any.  Set to nullptr if
137      * no configuration changes are defined for this rail.
138      */
139     std::unique_ptr<Configuration> configuration{};
140 
141     /**
142      * Sensor monitoring for this rail, if any.  Set to nullptr if no sensor
143      * monitoring is defined for this rail.
144      */
145     std::unique_ptr<SensorMonitoring> sensorMonitoring{};
146 };
147 
148 } // namespace phosphor::power::regulators
149