Documentation only, no functional change
Added copyrights and comments within headers
Resolves openbmc/openbmc#959
Change-Id: If58d78a39fb08251a34a88c2b6340c9fa33d2569
Signed-off-by: Matthew Barth <msbarth@us.ibm.com>
diff --git a/fan_enclosure.cpp b/fan_enclosure.cpp
index aaf415d..b015ac6 100644
--- a/fan_enclosure.cpp
+++ b/fan_enclosure.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 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.
+ */
#include <algorithm>
#include <phosphor-logging/log.hpp>
#include "fan_enclosure.hpp"
diff --git a/fan_enclosure.hpp b/fan_enclosure.hpp
index da6f7e5..1c8d241 100644
--- a/fan_enclosure.hpp
+++ b/fan_enclosure.hpp
@@ -12,6 +12,9 @@
namespace presence
{
+/**
+ * @brief Specifies the defined presence states of a fan enclosure
+ */
typedef enum presenceState
{
NOT_PRESENT,
@@ -19,6 +22,13 @@
UNKNOWN
} presenceState;
+/**
+ * @class FanEnclosure
+ * @brief OpenBMC fan enclosure inventory presence implementation
+ * @details Inventory is based on the fan enclosure being present or not. This
+ * class represents that fan enclosure and updates its presences status within
+ * its inventory object based on the status of all its sensors.
+ */
class FanEnclosure
{
using Property = std::string;
@@ -40,6 +50,12 @@
FanEnclosure& operator=(FanEnclosure&&) = delete;
~FanEnclosure() = default;
+ /**
+ * @brief Constructs Fan Enclosure Object
+ *
+ * @param[in] bus - Dbus bus object
+ * @param[in] fanProp - Fan enclosure properties
+ */
FanEnclosure(sdbusplus::bus::bus& bus,
const phosphor::fan::Properties& fanProp) :
bus(bus),
@@ -50,20 +66,51 @@
updInventory();
}
+ /**
+ * @brief Update inventory when the determined presence of this fan
+ * enclosure has changed
+ */
void updInventory();
+ /**
+ * @brief Add a sensor association to this fan enclosure
+ *
+ * @param[in] sensor - Sensor associated to this fan enclosure
+ */
void addSensor(
std::unique_ptr<Sensor>&& sensor);
private:
+ /** @brief Connection for sdbusplus bus */
sdbusplus::bus::bus& bus;
+ /** @brief Inventory path for this fan enclosure */
const std::string invPath;
+ /** @brief Description used as 'PrettyName' on inventory object */
const std::string fanDesc;
+ /** @brief List of sensors associated with this fan enclosure */
std::vector<std::unique_ptr<Sensor>> sensors;
+ /** @brief Last known presence state of this fan enclosure */
presenceState presState = UNKNOWN;
+ /**
+ * @brief Get the current presence state based on all sensors
+ *
+ * @return Current presence state determined from all sensors
+ */
presenceState getCurPresState();
//TODO openbmc/openbmc#1299 - Move getInvService() to a utility file
+ /**
+ * @brief Get the inventory service name from the mapper object
+ *
+ * @return The inventory manager service name
+ */
std::string getInvService();
+ /**
+ * @brief Construct the inventory object map
+ *
+ * @param[in] Current presence state
+ *
+ * @return The inventory object map to update inventory
+ */
ObjectMap getObjectMap(bool curPresState);
};
diff --git a/fan_properties.hpp b/fan_properties.hpp
index 22d655a..296318d 100644
--- a/fan_properties.hpp
+++ b/fan_properties.hpp
@@ -10,6 +10,10 @@
namespace fan
{
+/**
+ * @brief Fan enclosure properties
+ * @details Contains the inventory path, description and list of sensors
+ */
using Properties = std::tuple<std::string,
std::string,
std::vector<std::string>>;
diff --git a/sensor_base.hpp b/sensor_base.hpp
index 2dc2b8d..c206e70 100644
--- a/sensor_base.hpp
+++ b/sensor_base.hpp
@@ -8,7 +8,14 @@
namespace presence
{
+// Forward declare FanEnclosure
class FanEnclosure;
+/**
+ * @class Sensor
+ * @brief Base sensor implementation to be extended
+ * @details A type of presence detection sensor would extend this to override
+ * how presences is determined by the fan enclosure containing that type
+ */
class Sensor
{
public:
@@ -19,6 +26,12 @@
Sensor& operator=(Sensor&&) = delete;
virtual ~Sensor() = default;
+ /**
+ * @brief Constructs Sensor Object
+ *
+ * @param[in] id - ID name of this sensor
+ * @param[in] fanEnc - Reference to the fan enclosure with this sensor
+ */
Sensor(const std::string& id,
FanEnclosure& fanEnc) :
id(id),
@@ -27,10 +40,16 @@
//Nothing to do here
}
+ /**
+ * @brief Presence function that must be implemented within the derived
+ * type of sensor's implementation on how presence is determined
+ */
virtual bool isPresent() = 0;
protected:
+ /** @brief ID name of this sensor */
const std::string id;
+ /** @brief Reference to the fan enclosure containing this sensor */
FanEnclosure& fanEnc;
};
diff --git a/tach_detect.cpp b/tach_detect.cpp
index 5da1b48..2449f82 100644
--- a/tach_detect.cpp
+++ b/tach_detect.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 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.
+ */
#include <vector>
#include <sdbusplus/bus.hpp>
#include "fan_enclosure.hpp"
diff --git a/tach_sensor.cpp b/tach_sensor.cpp
index 91e249d..c21478b 100644
--- a/tach_sensor.cpp
+++ b/tach_sensor.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 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.
+ */
#include <sdbusplus/exception.hpp>
#include "tach_sensor.hpp"
#include "fan_enclosure.hpp"
diff --git a/tach_sensor.hpp b/tach_sensor.hpp
index b9ac9b3..90d955b 100644
--- a/tach_sensor.hpp
+++ b/tach_sensor.hpp
@@ -12,6 +12,12 @@
namespace presence
{
+/**
+ * @class TachSensor
+ * @brief OpenBMC Tach feedback sensor presence implementation
+ * @details Derived sensor type that uses the tach feedback value to determine
+ * the presence of the fan enclosure that contains this sensor
+ */
class TachSensor : public Sensor
{
public:
@@ -22,6 +28,13 @@
TachSensor& operator=(TachSensor&&) = delete;
~TachSensor() = default;
+ /**
+ * @brief Constructs Tach Sensor Object
+ *
+ * @param[in] bus - Dbus bus object
+ * @param[in] id - ID name of this sensor
+ * @param[in] fanEnc - Reference to the fan enclosure with this sensor
+ */
TachSensor(
sdbusplus::bus::bus& bus,
const std::string& id,
@@ -36,14 +49,29 @@
// Nothing to do here
}
+ /**
+ * @brief Determine the presence of this sensor using the tach feedback
+ *
+ * @return Presence state based on tach feedback
+ */
bool isPresent();
private:
+ /** @brief Connection for sdbusplus bus */
sdbusplus::bus::bus& bus;
+ /** @brief Used to subscribe to dbus signals */
sdbusplus::server::match::match tachSignal;
+ /** @brief Tach speed value given from the signal */
int64_t tach = 0;
- static std::string match(std::string id)
+ /**
+ * @brief Appends the fan sensor id to construct a match string
+ *
+ * @param[in] id - Fan sensor id
+ *
+ * @return Match string to register signal for the fan sensor id
+ */
+ static std::string match(const std::string& id)
{
return std::string("type='signal',"
"interface='org.freedesktop.DBus.Properties',"
@@ -51,11 +79,24 @@
"path='/xyz/openbmc_project/sensors/fan_tach/" +
id + "'");
}
- // Tach signal callback handler
+ /**
+ * @brief Callback function on tach change signals
+ *
+ * @param[out] msg - Data associated with the subscribed signal
+ * @param[out] data - Pointer to this tach sensor object instance
+ * @param[out] err - Contains any sdbus error reference if occurred
+ *
+ * @return 0
+ */
static int handleTachChangeSignal(sd_bus_message* msg,
void* data,
sd_bus_error* err);
-
+ /**
+ * @brief Determine & handle when the signal was a tach change
+ *
+ * @param[in] msg - Expanded sdbusplus message data
+ * @param[in] err - Contains any sdbus error reference if occurred
+ */
void handleTachChange(sdbusplus::message::message& msg,
sd_bus_error* err);