15ad53945SShawn McCarney /** 25ad53945SShawn McCarney * Copyright © 2020 IBM Corporation 35ad53945SShawn McCarney * 45ad53945SShawn McCarney * Licensed under the Apache License, Version 2.0 (the "License"); 55ad53945SShawn McCarney * you may not use this file except in compliance with the License. 65ad53945SShawn McCarney * You may obtain a copy of the License at 75ad53945SShawn McCarney * 85ad53945SShawn McCarney * http://www.apache.org/licenses/LICENSE-2.0 95ad53945SShawn McCarney * 105ad53945SShawn McCarney * Unless required by applicable law or agreed to in writing, software 115ad53945SShawn McCarney * distributed under the License is distributed on an "AS IS" BASIS, 125ad53945SShawn McCarney * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 135ad53945SShawn McCarney * See the License for the specific language governing permissions and 145ad53945SShawn McCarney * limitations under the License. 155ad53945SShawn McCarney */ 165ad53945SShawn McCarney #pragma once 175ad53945SShawn McCarney 185ad53945SShawn McCarney #include "action_environment.hpp" 195ad53945SShawn McCarney #include "i2c_action.hpp" 205ad53945SShawn McCarney 215ad53945SShawn McCarney #include <cstdint> 225ad53945SShawn McCarney #include <stdexcept> 235ad53945SShawn McCarney #include <string> 245ad53945SShawn McCarney #include <vector> 255ad53945SShawn McCarney 265ad53945SShawn McCarney namespace phosphor::power::regulators 275ad53945SShawn McCarney { 285ad53945SShawn McCarney 295ad53945SShawn McCarney /** 305ad53945SShawn McCarney * @class I2CCompareBytesAction 315ad53945SShawn McCarney * 325ad53945SShawn McCarney * Compares device register bytes to a list of expected values. Communicates 335ad53945SShawn McCarney * with the device directly using the I2C interface. 345ad53945SShawn McCarney * 355ad53945SShawn McCarney * Implements the i2c_compare_bytes action in the JSON config file. 365ad53945SShawn McCarney */ 375ad53945SShawn McCarney class I2CCompareBytesAction : public I2CAction 385ad53945SShawn McCarney { 395ad53945SShawn McCarney public: 405ad53945SShawn McCarney // Specify which compiler-generated methods we want 415ad53945SShawn McCarney I2CCompareBytesAction() = delete; 425ad53945SShawn McCarney I2CCompareBytesAction(const I2CCompareBytesAction&) = delete; 435ad53945SShawn McCarney I2CCompareBytesAction(I2CCompareBytesAction&&) = delete; 445ad53945SShawn McCarney I2CCompareBytesAction& operator=(const I2CCompareBytesAction&) = delete; 455ad53945SShawn McCarney I2CCompareBytesAction& operator=(I2CCompareBytesAction&&) = delete; 465ad53945SShawn McCarney virtual ~I2CCompareBytesAction() = default; 475ad53945SShawn McCarney 485ad53945SShawn McCarney /** 495ad53945SShawn McCarney * Constructor. 505ad53945SShawn McCarney * 515ad53945SShawn McCarney * Throws an exception if any of the input parameters are invalid. 525ad53945SShawn McCarney * 535ad53945SShawn McCarney * @param reg Device register address. Note: named 'reg' because 'register' 545ad53945SShawn McCarney * is a reserved keyword. 555ad53945SShawn McCarney * @param values One or more expected byte values. The bytes must be 565ad53945SShawn McCarney * specified in the same order as they will be received from 575ad53945SShawn McCarney * the device (e.g. in little-endian order). 585ad53945SShawn McCarney */ I2CCompareBytesAction(uint8_t reg,const std::vector<uint8_t> & values)595ad53945SShawn McCarney explicit I2CCompareBytesAction(uint8_t reg, 605ad53945SShawn McCarney const std::vector<uint8_t>& values) : 615ad53945SShawn McCarney I2CCompareBytesAction(reg, values, 625ad53945SShawn McCarney std::vector<uint8_t>(values.size(), 0xFF)) 63*0c9a33d6SAdriana Kobylak {} 645ad53945SShawn McCarney 655ad53945SShawn McCarney /** 665ad53945SShawn McCarney * Constructor. 675ad53945SShawn McCarney * 685ad53945SShawn McCarney * Throws an exception if any of the input parameters are invalid. 695ad53945SShawn McCarney * 705ad53945SShawn McCarney * @param reg Device register address. Note: named 'reg' because 'register' 715ad53945SShawn McCarney * is a reserved keyword. 725ad53945SShawn McCarney * @param values One or more expected byte values. The bytes must be 735ad53945SShawn McCarney * specified in the same order as they will be received from 745ad53945SShawn McCarney * the device (e.g. in little-endian order). 755ad53945SShawn McCarney * @param masks One or more bit masks. The number of bit masks must match 765ad53945SShawn McCarney * the number of expected byte values. Each mask specifies 775ad53945SShawn McCarney * which bits should be compared within the corresponding byte 785ad53945SShawn McCarney * value. Only the bits with a value of 1 in the mask will be 795ad53945SShawn McCarney * compared. 805ad53945SShawn McCarney */ I2CCompareBytesAction(uint8_t reg,const std::vector<uint8_t> & values,const std::vector<uint8_t> & masks)815ad53945SShawn McCarney explicit I2CCompareBytesAction(uint8_t reg, 825ad53945SShawn McCarney const std::vector<uint8_t>& values, 835ad53945SShawn McCarney const std::vector<uint8_t>& masks) : 845ad53945SShawn McCarney reg{reg}, 855ad53945SShawn McCarney values{values}, masks{masks} 865ad53945SShawn McCarney { 875ad53945SShawn McCarney // Values vector must not be empty 885ad53945SShawn McCarney if (values.size() < 1) 895ad53945SShawn McCarney { 905ad53945SShawn McCarney throw std::invalid_argument{"Values vector is empty"}; 915ad53945SShawn McCarney } 925ad53945SShawn McCarney 935ad53945SShawn McCarney // Masks vector must have same size as values vector 945ad53945SShawn McCarney if (masks.size() != values.size()) 955ad53945SShawn McCarney { 965ad53945SShawn McCarney throw std::invalid_argument{"Masks vector has invalid size"}; 975ad53945SShawn McCarney } 985ad53945SShawn McCarney } 995ad53945SShawn McCarney 1005ad53945SShawn McCarney /** 1015ad53945SShawn McCarney * Executes this action. 1025ad53945SShawn McCarney * 1035ad53945SShawn McCarney * Compares device register bytes to a list of expected values using the 1045ad53945SShawn McCarney * I2C interface. 1055ad53945SShawn McCarney * 1065ad53945SShawn McCarney * All of the bytes will be read in a single I2C operation. 1075ad53945SShawn McCarney * 1085ad53945SShawn McCarney * The device register, byte values, and bit masks (if any) were specified 1095ad53945SShawn McCarney * in the constructor. 1105ad53945SShawn McCarney * 1115ad53945SShawn McCarney * The device is obtained from the specified action environment. 1125ad53945SShawn McCarney * 1135ad53945SShawn McCarney * Throws an exception if an error occurs. 1145ad53945SShawn McCarney * 1155ad53945SShawn McCarney * @param environment action execution environment 1165ad53945SShawn McCarney * @return true if the register bytes contained the expected values, 1175ad53945SShawn McCarney * otherwise returns false. 1185ad53945SShawn McCarney */ 1195ad53945SShawn McCarney virtual bool execute(ActionEnvironment& environment) override; 1205ad53945SShawn McCarney 1215ad53945SShawn McCarney /** 1225ad53945SShawn McCarney * Returns the device register address. 1235ad53945SShawn McCarney * 1245ad53945SShawn McCarney * @return register address 1255ad53945SShawn McCarney */ getRegister() const1265ad53945SShawn McCarney uint8_t getRegister() const 1275ad53945SShawn McCarney { 1285ad53945SShawn McCarney return reg; 1295ad53945SShawn McCarney } 1305ad53945SShawn McCarney 1315ad53945SShawn McCarney /** 1325ad53945SShawn McCarney * Returns the expected byte values. 1335ad53945SShawn McCarney * 1345ad53945SShawn McCarney * @return expected values 1355ad53945SShawn McCarney */ getValues() const1365ad53945SShawn McCarney const std::vector<uint8_t>& getValues() const 1375ad53945SShawn McCarney { 1385ad53945SShawn McCarney return values; 1395ad53945SShawn McCarney } 1405ad53945SShawn McCarney 1415ad53945SShawn McCarney /** 1425ad53945SShawn McCarney * Returns the bit masks. 1435ad53945SShawn McCarney * 1445ad53945SShawn McCarney * Each mask specifies which bits should be compared within the 1455ad53945SShawn McCarney * corresponding byte value. Only the bits with a value of 1 in the mask 1465ad53945SShawn McCarney * will be compared. 1475ad53945SShawn McCarney * 1485ad53945SShawn McCarney * @return bit masks 1495ad53945SShawn McCarney */ getMasks() const1505ad53945SShawn McCarney const std::vector<uint8_t>& getMasks() const 1515ad53945SShawn McCarney { 1525ad53945SShawn McCarney return masks; 1535ad53945SShawn McCarney } 1545ad53945SShawn McCarney 1555ad53945SShawn McCarney /** 1565ad53945SShawn McCarney * Returns a string description of this action. 1575ad53945SShawn McCarney * 1585ad53945SShawn McCarney * @return description of action 1595ad53945SShawn McCarney */ 1605ad53945SShawn McCarney virtual std::string toString() const override; 1615ad53945SShawn McCarney 1625ad53945SShawn McCarney private: 1635ad53945SShawn McCarney /** 1645ad53945SShawn McCarney * Device register address. Note: named 'reg' because 'register' is a 1655ad53945SShawn McCarney * reserved keyword. 1665ad53945SShawn McCarney */ 1675ad53945SShawn McCarney const uint8_t reg{0x00}; 1685ad53945SShawn McCarney 1695ad53945SShawn McCarney /** 1705ad53945SShawn McCarney * Expected byte values. 1715ad53945SShawn McCarney */ 1725ad53945SShawn McCarney const std::vector<uint8_t> values{}; 1735ad53945SShawn McCarney 1745ad53945SShawn McCarney /** 1755ad53945SShawn McCarney * Bit masks. Each mask specifies which bits should be compared within the 1765ad53945SShawn McCarney * corresponding byte value. Only the bits with a value of 1 in the mask 1775ad53945SShawn McCarney * will be compared. 1785ad53945SShawn McCarney */ 1795ad53945SShawn McCarney const std::vector<uint8_t> masks{}; 1805ad53945SShawn McCarney }; 1815ad53945SShawn McCarney 1825ad53945SShawn McCarney } // namespace phosphor::power::regulators 183