pseq: Create base class for sequencer devices
Create an abstract base class representing a power sequencer device.
These devices turn on voltage rails in the correct sequence and monitor
the rails for power good faults.
Create a mock subclass to support automated testing.
Change-Id: I97d0befde9896dc050ec757c4004dca70f135554
Signed-off-by: Shawn McCarney <shawnmm@us.ibm.com>
diff --git a/phosphor-power-sequencer/src/power_sequencer_device.hpp b/phosphor-power-sequencer/src/power_sequencer_device.hpp
new file mode 100644
index 0000000..e7ec274
--- /dev/null
+++ b/phosphor-power-sequencer/src/power_sequencer_device.hpp
@@ -0,0 +1,161 @@
+/**
+ * Copyright © 2024 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include "services.hpp"
+
+#include <cstdint>
+#include <map>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace phosphor::power::sequencer
+{
+
+/**
+ * @class PowerSequencerDevice
+ *
+ * Abstract base class for a hardware device that performs the following tasks:
+ * - Enables (turns on) the voltage rails in the proper sequence
+ * - Checks the pgood (power good) status of each voltage rail
+ */
+class PowerSequencerDevice
+{
+ public:
+ // Specify which compiler-generated methods we want
+ PowerSequencerDevice() = default;
+ PowerSequencerDevice(const PowerSequencerDevice&) = delete;
+ PowerSequencerDevice(PowerSequencerDevice&&) = delete;
+ PowerSequencerDevice& operator=(const PowerSequencerDevice&) = delete;
+ PowerSequencerDevice& operator=(PowerSequencerDevice&&) = delete;
+ virtual ~PowerSequencerDevice() = default;
+
+ /**
+ * Returns the device name.
+ *
+ * @return device name
+ */
+ virtual const std::string& getName() const = 0;
+
+ /**
+ * Returns the GPIO values that can be read from the device.
+ *
+ * The vector indices correspond to the libgpiod line offsets. For example,
+ * the element at vector index 0 is the GPIO value at libgpiod line offset
+ * 0. These offsets may correspond to logical pin IDs, but they are usually
+ * different from the physical pin numbers on the device. Consult the
+ * device documentation for more information.
+ *
+ * Throws an exception if the values could not be read or the device does
+ * not support GPIO values.
+ *
+ * @return GPIO values
+ */
+ virtual std::vector<int> getGPIOValues() = 0;
+
+ /**
+ * Returns the value of the PMBus STATUS_WORD command for the specified
+ * PMBus page.
+ *
+ * The returned value is in host-endian order.
+ *
+ * Throws an exception if the value could not be obtained or the device does
+ * not support the STATUS_WORD command.
+ *
+ * @param page PMBus page
+ * @return STATUS_WORD value
+ */
+ virtual uint16_t getStatusWord(uint8_t page) = 0;
+
+ /**
+ * Returns the value of the PMBus STATUS_VOUT command for the specified
+ * PMBus page.
+ *
+ * Throws an exception if the value could not be obtained or the device does
+ * not support the STATUS_VOUT command.
+ *
+ * @param page PMBus page
+ * @return STATUS_VOUT value
+ */
+ virtual uint8_t getStatusVout(uint8_t page) = 0;
+
+ /**
+ * Returns the value of the PMBus READ_VOUT command for the specified
+ * PMBus page.
+ *
+ * The returned value is in Volts.
+ *
+ * Throws an exception if the value could not be obtained or the device does
+ * not support the READ_VOUT command.
+ *
+ * @param page PMBus page
+ * @return READ_VOUT value in volts
+ */
+ virtual double getReadVout(uint8_t page) = 0;
+
+ /**
+ * Returns the value of the PMBus VOUT_UV_FAULT_LIMIT command for the
+ * specified PMBus page.
+ *
+ * The returned value is in Volts.
+ *
+ * Throws an exception if the value could not be obtained or the device does
+ * not support the VOUT_UV_FAULT_LIMIT command.
+ *
+ * @param page PMBus page
+ * @return VOUT_UV_FAULT_LIMIT value in volts
+ */
+ virtual double getVoutUVFaultLimit(uint8_t page) = 0;
+
+ /**
+ * Returns the value of the PMBus VOUT_OV_FAULT_LIMIT command for the
+ * specified PMBus page.
+ *
+ * The returned value is in Volts.
+ *
+ * Throws an exception if the value could not be obtained or the device does
+ * not support the VOUT_OV_FAULT_LIMIT command.
+ *
+ * @param page PMBus page
+ * @return VOUT_OV_FAULT_LIMIT value in volts
+ */
+ virtual double getVoutOVFaultLimit(uint8_t page) = 0;
+
+ /**
+ * Returns whether a pgood fault has occurred on one of the rails being
+ * monitored by this device.
+ *
+ * Throws an exception if an error occurs while trying to obtain the status
+ * of the rails.
+ *
+ * @param powerSupplyError Power supply error that occurred before the pgood
+ * fault. Set to the empty string if no power
+ * supply error occurred. This error may be the
+ * root cause if a pgood fault occurred on a power
+ * supply rail monitored by this device.
+ * @param error Error that should be logged if this method returns true.
+ * @param additionalData Additional data to include in the error log if
+ * this method returns true.
+ * @return true if a pgood fault was found on a rail monitored by this
+ * device, false otherwise
+ */
+ virtual bool
+ hasPgoodFault(const std::string& powerSupplyError, std::string& error,
+ std::map<std::string, std::string>& additionalData) = 0;
+};
+
+} // namespace phosphor::power::sequencer
diff --git a/phosphor-power-sequencer/test/mock_device.hpp b/phosphor-power-sequencer/test/mock_device.hpp
new file mode 100644
index 0000000..2d2e0ca
--- /dev/null
+++ b/phosphor-power-sequencer/test/mock_device.hpp
@@ -0,0 +1,54 @@
+/**
+ * Copyright © 2024 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#pragma once
+
+#include "power_sequencer_device.hpp"
+
+#include <gmock/gmock.h>
+
+namespace phosphor::power::sequencer
+{
+
+/**
+ * @class MockDevice
+ *
+ * Mock implementation of the PowerSequencerDevice interface.
+ */
+class MockDevice : public PowerSequencerDevice
+{
+ public:
+ // Specify which compiler-generated methods we want
+ MockDevice() = default;
+ MockDevice(const MockDevice&) = delete;
+ MockDevice(MockDevice&&) = delete;
+ MockDevice& operator=(const MockDevice&) = delete;
+ MockDevice& operator=(MockDevice&&) = delete;
+ virtual ~MockDevice() = default;
+
+ MOCK_METHOD(const std::string&, getName, (), (const, override));
+ MOCK_METHOD(std::vector<int>, getGPIOValues, (), (override));
+ MOCK_METHOD(uint16_t, getStatusWord, (uint8_t page), (override));
+ MOCK_METHOD(uint8_t, getStatusVout, (uint8_t page), (override));
+ MOCK_METHOD(double, getReadVout, (uint8_t page), (override));
+ MOCK_METHOD(double, getVoutUVFaultLimit, (uint8_t page), (override));
+ MOCK_METHOD(double, getVoutOVFaultLimit, (uint8_t page), (override));
+ MOCK_METHOD(bool, hasPgoodFault,
+ (const std::string& powerSupplyError, std::string& error,
+ std::map<std::string, std::string>& additionalData),
+ (override));
+};
+
+} // namespace phosphor::power::sequencer