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_environment.hpp"
19 #include "i2c_action.hpp"
20 
21 #include <cstdint>
22 #include <string>
23 
24 namespace phosphor::power::regulators
25 {
26 
27 /**
28  * @class I2CCompareByteAction
29  *
30  * Compares a device register to a byte value.  Communicates with the device
31  * directly using the I2C interface.
32  *
33  * Implements the i2c_compare_byte action in the JSON config file.
34  */
35 class I2CCompareByteAction : public I2CAction
36 {
37   public:
38     // Specify which compiler-generated methods we want
39     I2CCompareByteAction() = delete;
40     I2CCompareByteAction(const I2CCompareByteAction&) = delete;
41     I2CCompareByteAction(I2CCompareByteAction&&) = delete;
42     I2CCompareByteAction& operator=(const I2CCompareByteAction&) = delete;
43     I2CCompareByteAction& operator=(I2CCompareByteAction&&) = delete;
44     virtual ~I2CCompareByteAction() = default;
45 
46     /**
47      * Constructor.
48      *
49      * @param reg Device register address.  Note: named 'reg' because 'register'
50      *            is a reserved keyword.
51      * @param value Expected byte value.
52      * @param mask Bit mask.  Specifies which bits should be compared within the
53      *             byte value.  Only the bits with a value of 1 in the mask will
54      *             be compared.  If not specified, defaults to 0xFF which means
55      *             that all bits will be compared.
56      */
I2CCompareByteAction(uint8_t reg,uint8_t value,uint8_t mask=0xFF)57     explicit I2CCompareByteAction(uint8_t reg, uint8_t value,
58                                   uint8_t mask = 0xFF) :
59         reg{reg}, value{value}, mask{mask}
60     {}
61 
62     /**
63      * Executes this action.
64      *
65      * Compares a device register to a byte value using the I2C interface.
66      *
67      * The device register, byte value, and mask (if any) were specified in the
68      * constructor.
69      *
70      * The device is obtained from the specified action environment.
71      *
72      * Throws an exception if an error occurs.
73      *
74      * @param environment action execution environment
75      * @return true if the register contained the expected value, otherwise
76      *         returns false.
77      */
78     virtual bool execute(ActionEnvironment& environment) override;
79 
80     /**
81      * Returns the device register address.
82      *
83      * @return register address
84      */
getRegister() const85     uint8_t getRegister() const
86     {
87         return reg;
88     }
89 
90     /**
91      * Returns the expected byte value.
92      *
93      * @return expected value
94      */
getValue() const95     uint8_t getValue() const
96     {
97         return value;
98     }
99 
100     /**
101      * Returns the bit mask.
102      *
103      * Specifies which bits should be compared within the byte value.  Only the
104      * bits with a value of 1 in the mask will be compared.
105      *
106      * @return bit mask
107      */
getMask() const108     uint8_t getMask() const
109     {
110         return mask;
111     }
112 
113     /**
114      * Returns a string description of this action.
115      *
116      * @return description of action
117      */
118     virtual std::string toString() const override;
119 
120   private:
121     /**
122      * Device register address.  Note: named 'reg' because 'register' is a
123      * reserved keyword.
124      */
125     const uint8_t reg{0x00};
126 
127     /**
128      * Expected byte value.
129      */
130     const uint8_t value{0x00};
131 
132     /**
133      * Bit mask.  Specifies which bits should be compared within the byte value.
134      * Only the bits with a value of 1 in the mask will be compared.
135      */
136     const uint8_t mask{0xFF};
137 };
138 
139 } // namespace phosphor::power::regulators
140