diff options
Diffstat (limited to 'src/include/usr/targeting/common')
18 files changed, 3226 insertions, 0 deletions
diff --git a/src/include/usr/targeting/common/attributes.H b/src/include/usr/targeting/common/attributes.H new file mode 100644 index 000000000..d760fb19f --- /dev/null +++ b/src/include/usr/targeting/common/attributes.H @@ -0,0 +1,52 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/attributes.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_ATTRIBUTES_H +#define __TARGETING_COMMON_ATTRIBUTES_H + +/** + * @file targeting/common/attributes.H + * + * @brief Enums/type/properties of platform specific attributes + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <stdint.h> +#include <stdlib.h> + +// This component +#include <builtins.h> +#include <targeting/adapters/types.H> +#include <attributeenums.H> +#include <targeting/common/entitypath.H> +#include <attributestructs.H> +#include <attributetraits.H> +#include <attributestrings.H> +#include <targeting/common/target.H> +#include <targeting/common/util.H> + +#endif // __TARGETING_COMMON_ATTRIBUTES_H diff --git a/src/include/usr/targeting/common/commontargeting.H b/src/include/usr/targeting/common/commontargeting.H new file mode 100644 index 000000000..c1a52a703 --- /dev/null +++ b/src/include/usr/targeting/common/commontargeting.H @@ -0,0 +1,45 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/common/commontargeting.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_COMMONTARGETING_H +#define __TARGETING_COMMON_COMMONTARGETING_H + +/** + * @file targeting/common/commontargeting.H + * + * @brief Aggregation of all other major exported common targeting header files + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +#include <targeting/common/targreasoncodes.H> +#include <targeting/common/attributes.H> +#include <targeting/common/iterators/iterators.H> +#include <targeting/common/predicates/predicates.H> +#include <targeting/common/targetservice.H> + +// Please keep up to date + +#endif // __TARGETING_COMMON_COMMONTARGETING_H diff --git a/src/include/usr/targeting/common/entitypath.H b/src/include/usr/targeting/common/entitypath.H new file mode 100644 index 000000000..5d46af493 --- /dev/null +++ b/src/include/usr/targeting/common/entitypath.H @@ -0,0 +1,451 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/entitypath.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_ENTITYPATH_H +#define __TARGETING_COMMON_ENTITYPATH_H + +/** + * @file targeting/common/entitypath.H + * + * @brief Interface for the EntityPath class + * + * This header file contains the interface for the EntityPath class which + * supports hierarchical path representation of various flavors + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <stdint.h> +#include <stdlib.h> +#include <vector> + +namespace TARGETING +{ + +class Target; + +/** + * @brief Entity path class which represents a target's relationship(s) to + * other targets + * + * Entity path class which represents a target's relationship(s) to other + * targets via hierarchical paths. Entity paths can represent different + * relationships, such as logical containment (where part X contains part Y + * contains part Z), hardware affinity, etc. An entity path is composed of + * a number of type/instance pairs that represent a given target in a given + * hierarchy. In the logical containment example, part Z's logical containment + * path would look something like partX-0/partY-1/partZ-0. + */ +class EntityPath +{ + public: + + /** + * @brief Maximum number of path elements than an entity path can have + */ + enum + { + MAX_PATH_ELEMENTS = 10, + }; + + /** + * @brief Entity Path Types + * + * An entity path type indicates which specific set of relationships is + * modeled by a particular entity path. For example, PATH_AFFINITY + * models how targets are connected to each other from a hardware + * affinity perspective. + */ + enum PATH_TYPE + { + PATH_NA = 0x00, ///< Not applicable + PATH_AFFINITY = 0x01, ///< Entity path models hardware affinity + ///< relationships + PATH_PHYSICAL = 0x02, ///< Entity path models logical containment + ///< relationships + PATH_DEVICE = 0x03, ///< Entity path models a device driver path + PATH_POWER = 0x04, ///< Entity path models power provider and + ///< power consumer relationships + }; + + /** + * @brief Entity Path Element Definition + * + * Any entity path models one level of an entity path hierarchy + */ + struct PathElement + { + TYPE type : 8; ///< Type of element at this level in the hierarchy + uint8_t instance; ///< Instance ID for the element, relative to + ///< the parent + + } PACKED; + + /** + * @brief Creates an entity path object, based on path type + * + * Creates an entity path of the specified type, but does not populate + * it with any path elements. + * + * @param[in] i_pathType Type of entity path to create + * + * @post Entity path of specified type created with no path elements + */ + EntityPath( + PATH_TYPE i_pathType); + + /** + * @brief Creates an empty entity path object + * + * Creates an empty entity path of N/A type and does not populate it + * with any path elements. The caller must initialize the type and + * populate it with path elements as needed + * + * @post Entity path created with default type and no path elements + */ + EntityPath(); + + /** + * @brief Destroys an entity path object + * + * Destroys an entity path object and frees all resources it + * exclusively owns. + * + * @post Entity path destroyed and all previously owned exclusive + * resources freed + */ + ~EntityPath(); + + /** + * @brief Removes/clears the last path element from an entity path + * + * Removes/clears the last path element from an entity path. If the + * caller attempts this operation and no path elements exist, the + * routine asserts. + * + * @post Entity path element removed from path + * + * @return Reference to the same EntityPath, for chaining + */ + EntityPath& removeLast(); + + /** + * @brief Returns a copy of the entity path with the last path + * element removed. The original entity path is not altered + * + * Returns a copy of the entity path with the last path + * element removed, useful for non-destructive transformations. + * caller attempts this operation and no path elements exist, the + * routine asserts. The original entity path is not altered. + * Equivalent to p1 = p2; p1.removeLast(); + * + * @post Copy of entity path with last element removed returned + * + * @return Copy of the EntityPath + */ + EntityPath copyRemoveLast() const; + + /** + * @brief Adds a path element to the end of an existing entity path + * object + * + * Adds a path element to the end of an existing entity path object. + * If the new path exceeds the maximum allowable number of path + * elements, the routine asserts + * + * @param[in] i_type Type of path element to add + * @param[in] i_instance Instance # of path element to add + * + * @pre N/A + * + * @post Entity path will increased by one path element, as specified + * by the input parameters + * + * @return Reference to the larger entity path + */ + EntityPath& addLast( + TYPE i_type, + uint8_t i_instance); + + /** + * @brief Returns a copy of the entity path with the specified + * path element added to the end. The original entity path is not + * altered + * + * Returns a copy of the entity path with the specified path element + * added to the end. If the new path exceeds the maximum allowable + * number of path elements, the routine asserts. The original entity + * path is not altered. Equivalent to p1 = p2. p1.addLast(..); + * + * @param[in] i_type Type of path element to add + * @param[in] i_instance Instance # of path element to add + * + * @pre N/A + * + * @post Copy of entity path with additional path element returned to + * caller + * + * @return Copy of the entity path with an additional path element + */ + EntityPath copyAddLast( + TYPE i_type, + uint8_t i_instance) const; + + /** + * @brief Returns a target handle to the target referred to by the + * entity path object + * + * Returns a target handle to the target referred to by the + * entity path object if it exists (NULL otherwise) + * + * @pre N/A + * + * @post Target handle returned to caller or NULL (if related target + * doesn't exist) + * + * @return Target handle + * + * @retval NULL Target doesn't exist + * @retval !NULL Target handle to the target referred to by the entity + * path + */ + Target* operator->(void); + + /** + * @brief Returns whether two entity paths are logically equal + * + * Returns whether two entity paths are logically equal. This + * determination takes into account the entity path type, the number + * of path elements, and the values of the path elements themselves. + * + * @param[in] i_rhs Const reference to entity path to compare + * + * @pre N/A + * + * @post Equality returned to caller + * + * @return bool indicating whether two entity paths are logically equal + * + * @retval true The entity paths are logically equal + * @retval false The entity paths are not logically equal + */ + bool operator==( + const EntityPath& i_rhs) const; + + /** + * @brief Returns whether two entity paths are logically equal, but + * only for the specified number of path elements + * + * Returns whether two entity paths are logically equal, but only for + * the specified number of path elements. This determination takes + * into account the entity path type, the specified number of path + * elements, and the values of the subset of path elements to be + * compared. For example, a device path of + * fsi0/cfam0/fsi0/cfam1/engine0 is equal to fsi0/cfam0 if the + * specified number of path elements is 1 or 2. + * + * @param[in] i_rhs Const reference to entity path to compare + * @param[in] i_size Number of path elements to compare; must be + * <= this->size() (otherwise routine will assert) + * + * @pre N/A + * + * @post Equality (for specified number of path elements) returned to + * caller + * + * @return bool indicating whether two entity paths are logically equal + * for the specified number of path elements (or assertion if + * specified size > this->size()) + * + * @retval true The entity paths are logically equal for the specified + * number of path elements + * @retval false The entity paths are not logically equal for the + * specified number of path elements + */ + bool equals( + const EntityPath& i_rhs, + uint32_t i_size) const; + + /** + * @brief Returns the path element at the specified index + * + * Returns the path element at the specified index (zero based). The + * routine will assert if the index exceeds this->size()-1; + * + * @param[in] i_index Path element to return (0 based indexing) + * + * @pre N/A + * + * @post Path element returned to caller on valid index. Assert + * triggered on invalid index. + * + * @return PathElement at the position in the entity path specified by + * index + */ + const PathElement& operator[]( + uint32_t i_index) const; + + /** + * @brief Returns the first path element of the given type + * + * Returns the first occurrence of a path element that matches the + * selected type. Will return a PathElement with type=TYPE_NA if + * no match is found. + * + * @param[in] i_type Element type to return + * + * @pre N/A + * + * @return PathElement of the given type else invalid PathElement + */ + const PathElement pathElementOfType( + const TYPE i_type) const; + + /** + * @brief Returns the number of path elements + * + * Returns the number of path elements for the entity path. + * + * @pre N/A + * + * @post Number of path elements returned to caller + * + * @return uint32_t giving the number of path elements + */ + uint32_t size() const; + + /** + * @brief Sets the path type + * + * Sets the path type for the entity path + * + * @param[in] i_pathType Path type specifier + * + * @pre N/A + * + * @post Path type set to the specified value + * + * @return N/A + */ + void setType( + PATH_TYPE i_pathType); + + /** + * @brief Returns the path type + * + * Returns the path type for the entity path + * + * @pre N/A + * + * @post Path type returned to caller + * + * @return PATH_TYPE indicating the entity path's path type + */ + PATH_TYPE type() const; + + /** + * @brief DEBUG ONLY. Returns the path type as a string. + * + * Returns the string encoding of the path type + * + * @pre N/A + * + * @post Path type string returned to caller + * + * @return String representation of the path type + */ + const char* pathTypeAsString() const; + + /** + * @brief DEBUG ONLY. Returns the path element type as a string. + * + * Returns the string encoding of the path element type + * + * @param[in] i_type Path element type to translate + * + * @pre N/A + * + * @post Path element type string returned to caller + * + * @return String representation of the path element type + */ + const char* pathElementTypeAsString( + TYPE i_type) const; + + /** + * @brief DEBUG ONLY. Returns the path element engine instance as a + * string. + * + * @param[in] i_engine Path element engine instance to translate + * + * Returns the string encoding of the path element engine instance + * + * @pre N/A + * + * @post Path element engine instance string returned to caller + * + * @return String representation of the path element engine instance + */ + const char* pathEngineInstanceAsString( + ENGINE_TYPE i_engine) const; + + /** + * @brief DEBUG ONLY. Dump the entity path + * + * Dumps the entity path + * + * @pre N/A + * + * @post Entity path dumped + * + * @return N/A + */ + void dump() const; + + /** + * @brief Save the entity path as a c-string + * + * @return The dynamic buffer (malloc'd) pointer of the c-string + * + * @note caller must call free() to release the buffer + */ + char * toString() const; + + private: + + PATH_TYPE iv_type : 4; ///< Entity path type (4 bits) + uint8_t iv_size : 4; ///< Number of path elements (4 bits) + PathElement iv_pathElement[MAX_PATH_ELEMENTS]; ///< Array of path + ///< elements + + // Compiler generated copy and assignment operators explicitly + // allowed and used + +} PACKED; + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_ENTITYPATH_H diff --git a/src/include/usr/targeting/common/error.H b/src/include/usr/targeting/common/error.H new file mode 100644 index 000000000..39153e6a7 --- /dev/null +++ b/src/include/usr/targeting/common/error.H @@ -0,0 +1,40 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/common/error.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_ERROR_H +#define __TARGETING_COMMON_ERROR_H + +/** + * @file targeting/common/error.H + * + * @brief Common header to abstract away error handling differences between + * platforms + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +#include <targeting/adapters/erroradapter.H> + +#endif // __TARGETING_COMMON_ERROR_H diff --git a/src/include/usr/targeting/common/iterators/iterators.H b/src/include/usr/targeting/common/iterators/iterators.H new file mode 100644 index 000000000..5339b33dd --- /dev/null +++ b/src/include/usr/targeting/common/iterators/iterators.H @@ -0,0 +1,39 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/common/iterators/iterators.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_ITERATORS_H +#define __TARGETING_COMMON_ITERATORS_H + +/** + * @file targeting/common/iterators/iterators.H + * + * @brief Header file which aggregates all the iterator header files. + */ + +#include <targeting/common/iterators/targetiterator.H> +#include <targeting/common/iterators/rangefilter.H> + +// please keep up to date... + +#endif // __TARGETING_COMMON_ITERATORS_H + diff --git a/src/include/usr/targeting/common/iterators/rangefilter.H b/src/include/usr/targeting/common/iterators/rangefilter.H new file mode 100644 index 000000000..b29cfa07d --- /dev/null +++ b/src/include/usr/targeting/common/iterators/rangefilter.H @@ -0,0 +1,341 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/iterators/rangefilter.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_RANGEFILTER_H +#define __TARGETING_COMMON_RANGEFILTER_H + +/** + * @file targeting/common/iterators/rangefilter.H + * + * @brief Interface describing an object which takes an iterator range and + * allows caller to iterate through the elements which match a supplied + * predicate (filter) + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD + +// Other Host Boot Components + +// Targeting Component +#include <targeting/common/target.H> +#include <targeting/common/predicates/predicatebase.H> +#include <targeting/common/iterators/targetiterator.H> + +//****************************************************************************** +// Macros +//****************************************************************************** + +#undef TARG_NAMESPACE +#undef TARG_CLASS +#undef TARG_FUNC + +//****************************************************************************** +// Interface +//****************************************************************************** + +namespace TARGETING +{ + +#define TARG_NAMESPACE "TARGETING::" + +#define TARG_CLASS "RangeFilter<IteratorType>::" + +/** + * @brief Templated class which which takes an iterator range of arbitrary type + * and allows caller to iterate through the elements which match a supplied + * predicate (filter) + */ +template<typename IteratorType> +class RangeFilter +{ + public: + + /** + * @var Forward the type of iterated elements to help build the + * class generically + */ + typedef typename IteratorType::value_type value_type; + + /** + * @var fake_bool is a pointer to a member function of RangeFilter + * which takes no arguments and returns void. + * Used to implement ability to check if range iterator is valid + */ + typedef void (RangeFilter::*fake_bool)() const; + + /** + * @brief Create a range object and locate first item in the range that + * matches the predicate (or the first if no predicate) + * + * @param[in] i_begin Iterator pointing to first item in range + * @param[in] i_end Iterator pointing to last item in range + * @param[in] i_pPredicate Predicate evaluated against each pointed to + * item + * + * @note Begin iterator must point to element prior to end iterator, + * otherwise result is undefined + */ + RangeFilter( + const IteratorType& i_begin, + const IteratorType& i_end, + const PredicateBase* i_pPredicate = NULL); + + /** + * @brief Destroy a range object (nothing to do) + */ + ~RangeFilter() + { + } + + /** + * @brief Dummy function used to implement ability to check if range + * iterator is valid + */ + operator fake_bool() const; + + /** + * @brief Pre-increment operator which advances the range's iterator + * to point to the next valid element + * + * @return Reference to this range filter + */ + RangeFilter& operator++(); + + /** + * @brief Dereference the range filter, returning the element pointed + * + * @return The element pointed to by the range filter + */ + value_type operator*() const + { + return *iv_current; + } + + /** + * @brief Dereference the range filter, returning the element pointed + * for use by the dereference and call member operator + * + * @return The element pointed to by the range filter + */ + value_type operator->() const + { + return *iv_current; + } + + /** + * @brief Reset the range's internal iterator to point to the first + * item in the range that matches the predicate (or the first if no + * predicate) + */ + void reset(); + + /** + * @brief Set the range's predicate filter + * + * @param[in] i_pPredicate Predicate to evaluate against elements + * pointed to by the range + */ + void setPredicate( + const PredicateBase* i_pPredicate); + + /** + * @brief Assignment operator; assign one range filter to another + * + * @param[in] i_rhs Range filter to assign + */ + RangeFilter& operator=( + const RangeFilter& i_rhs); + + /** + * @brief Copy constructor; create range filter using another range + * filter as a prototype for it + * + * @param[in] i_rhs Range filter to assign on create + */ + RangeFilter( + const RangeFilter& i_rhs); + + private: + + /** + * @brief Update internal cursor to point to the next element of the + * underlying range + * + * @note If the internal cursor is at the end of the range, then do + * nothing + */ + void advance(); + + /** + * @brief Update internal cursor to point to the next element of the + * underlying range only if not past the end of the range and the + * predicate doesn't match the current item + * + * @note If the internal cursor is at the end of the range, then do + * nothing + */ + void advanceIfNoMatch(); + + /** + * @brief Dummy function used to implement ability to check if range + * iterator is valid + */ + void notComparable() const + { + } + + IteratorType iv_current; ///< Iterator pointing to the + ///< current element + IteratorType iv_begin; ///< Iterator pointing to first + ///< element in range + IteratorType iv_end; ///< Iterator to past the end + ///< element in range + const PredicateBase* iv_pPredicate; ///< Range filter +}; + +typedef RangeFilter<TargetIterator> TargetRangeFilter; +typedef RangeFilter<ConstTargetIterator> ConstTargetRangeFilter; + +//****************************************************************************** +// RangeFilter::RangeFilter +//****************************************************************************** + +template<typename IteratorType> +RangeFilter<IteratorType>::RangeFilter( + const IteratorType& i_begin, + const IteratorType& i_end, + const PredicateBase* const i_pPredicate) +: iv_current(i_begin), + iv_begin(i_begin), + iv_end(i_end), + iv_pPredicate(i_pPredicate) +{ + advanceIfNoMatch(); +} + +//****************************************************************************** +// RangeFilter::operator= +//****************************************************************************** + +template<typename IteratorType> +RangeFilter<IteratorType>& RangeFilter<IteratorType>::operator=( + const RangeFilter& i_rhs) +{ + iv_current = i_rhs.iv_current; + iv_begin = i_rhs.iv_begin; + iv_end = i_rhs.iv_end; + iv_pPredicate = i_rhs.iv_pPredicate; +} + +//****************************************************************************** +// RangeFilter::RangeFilter (copy constructor) +//****************************************************************************** + +template<typename IteratorType> +RangeFilter<IteratorType>::RangeFilter( + const RangeFilter& i_rhs) +: iv_current(i_rhs.iv_current), + iv_begin(i_rhs.iv_begin), + iv_end(i_rhs.iv_end), + iv_pPredicate(i_rhs.iv_pPredicate) +{ +} + +//****************************************************************************** +// RangeFilter::setPredicate +//****************************************************************************** + +template<typename IteratorType> +void RangeFilter<IteratorType>::setPredicate( + const PredicateBase* const i_pPredicate) +{ + iv_pPredicate = i_pPredicate; + advanceIfNoMatch(); +} + +//****************************************************************************** +// RangeFilter::reset +//****************************************************************************** + +template<typename IteratorType> +void RangeFilter<IteratorType>::reset() +{ + iv_current = iv_begin; + advanceIfNoMatch(); +} + +//****************************************************************************** +// RangeFilter::operator++ +//****************************************************************************** + +template<typename IteratorType> +RangeFilter<IteratorType>& RangeFilter<IteratorType>::operator++() +{ + advance(); + return *this; +} + +/** + * @brief Disable meaningless "bool" comparisons that can occur when + * evaluating a range as a bool by forcing a compilation failure. + * Function interfaces not documented since they are not used. + */ +template <typename T> +bool operator!=(const TargetRangeFilter& i_lhs, const T& i_rhs) +{ + i_lhs.notComparable(); + return false; +} + +template <typename T> +bool operator==(const TargetRangeFilter& i_lhs, const T& i_rhs) +{ + i_lhs.notComparable(); + return false; +} + +template <typename T> +bool operator!=(const ConstTargetRangeFilter& i_lhs, const T& i_rhs) +{ + i_lhs.notComparable(); + return false; +} + +template <typename T> +bool operator==(const ConstTargetRangeFilter& i_lhs, const T& i_rhs) +{ + i_lhs.notComparable(); + return false; +} + +#undef TARG_CLASS +#undef TARG_NAMESPACE + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_RANGEFILTER + diff --git a/src/include/usr/targeting/common/iterators/targetiterator.H b/src/include/usr/targeting/common/iterators/targetiterator.H new file mode 100644 index 000000000..5abb21f81 --- /dev/null +++ b/src/include/usr/targeting/common/iterators/targetiterator.H @@ -0,0 +1,279 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/iterators/targetiterator.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_TARGETITERATOR_H +#define __TARGETING_COMMON_TARGETITERATOR_H + +/** + * @file targeting/common/iterators/targetiterator.H + * + * @brief Interface describing iterator/const iterator used to iterate through + * target service targets + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <stddef.h> + +// Other Host Boot Components +#include <builtins.h> + +// Targeting Component + +//****************************************************************************** +// Macros +//****************************************************************************** + +#undef TARG_NAMESPACE +#undef TARG_CLASS +#undef TARG_FUNC + +//****************************************************************************** +// Interface +//****************************************************************************** + +namespace TARGETING +{ + +#define TARG_NAMESPACE "TARGETING::" + +#define TARG_CLASS "_TargetIterator<T>::" + +class Target; + +/** + * @brief Class which iterates through targets managed by the target service. + * Provides "Target*" and "const Target*" versions via templates + */ +template<typename T> +class _TargetIterator +{ + public: + + /** + * @brief Maps type of iterated element to common alias (Target* or + * const Target*) + */ + typedef T iterator; + typedef T value_type; + + /** + * @brief Create an iterator to a (const/non-const) target handle. + * Defaults to end() + */ + ALWAYS_INLINE + _TargetIterator() + : iv_pCurrent(NULL) + { + } + + /** + * @brief Create an iterator to a (const/non-const) target handle + * + * @param[in] i_pTarget Target handle (pointer or const pointer + * depending on flavor) the iterator should reference + */ + ALWAYS_INLINE + explicit _TargetIterator(T i_pTarget) + : iv_pCurrent(i_pTarget) + { + } + + /** + * @brief Destroy an iterator to a (const/non-const) target handle + * + * @note Iterator does not own any resources to destroy + */ + ALWAYS_INLINE + ~_TargetIterator() + { + } + + /** + * @brief Dereference the iterator (return what it points to) + * + * @return Target handle in form of Target* or const Target* + * + * @note Returns NULL if it points to end(), should not be + * dereferenced in this case. + */ + ALWAYS_INLINE + T operator* () const + { + // Only return copy of the target pointer (instead of a reference) + // because a reference will go out of scope when the iterator + // advances + return iv_pCurrent; + } + + /** + * @brief Dereference the iterator (return what it points to) + * and (outside this function) call a function/member of + * the referenced target + * + * @return Target handle in form of Target* or const Target* + * + * @note Returns NULL if it points to end(), causing an + * assert when automatically dereferenced. + */ + ALWAYS_INLINE + T operator->() const + { + // Only return copy of the target pointer (instead of a reference) + // because a reference will go out of scope when the iterator + // advances + return iv_pCurrent; + } + + /** + * @brief Pre-increment the iterator + * + * @return The reference to the same iterator after advancing it + */ + ALWAYS_INLINE + _TargetIterator& operator++(); + + /** + * @brief Post-increment the iterator + * + * @param[in] UNNAMED Dummy parameter used to distinguish + * this interface from pre-increment + * + * @return Copy of the original iterator before it advanced + */ + ALWAYS_INLINE + _TargetIterator operator++(int); + + /** + * @brief Determine if two iterators of same type are logically equal + * + * @param[in] i_rhs The other iterator to compare + * + * @return bool indicating whether the iterators point to the same + * entity + * + * @retval true Iterators point to same entity + * @retval false Iterators do not point to same entity + */ + ALWAYS_INLINE + bool operator==(const _TargetIterator& i_rhs) const + { + return (iv_pCurrent == i_rhs.iv_pCurrent); + } + + /** + * @brief Determine if two iterators of same type are logically not + * equal + * + * @param[in] i_rhs The other iterator to compare + * + * @return bool indicating whether the iterators point to a different + * logical entity + * + * @retval true Iterators point to different entity + * @retval false Iterators point to same entity + */ + ALWAYS_INLINE + bool operator!=(const _TargetIterator& i_rhs) const + { + return (iv_pCurrent != i_rhs.iv_pCurrent); + } + + /** + * @brief Assignment operator; assign iterator to another (such that + * they logically point to same entity) + * + * @param[in] i_rhs The iterator to assign + * + * @return Reference to the iterator, now updated to point to the same + * entity as the input iterator points to + */ + ALWAYS_INLINE + _TargetIterator& operator=(const _TargetIterator& i_rhs) + { + iv_pCurrent = i_rhs.iv_pCurrent; + return *this; + } + + /** + * @brief Copy constructor; assign iterator to a new iterator (such + * that they logically point to same entity) + * + * @param[in] i_rhs The iterator to assign + */ + ALWAYS_INLINE + _TargetIterator(const _TargetIterator& i_rhs) + : iv_pCurrent(i_rhs.iv_pCurrent) + { + } + + private: + + /** + * @brief Advance the iterator to point to the next item maintained by + * the target service (or end() if end of list) + */ + void advance(); + + T iv_pCurrent; // Pointer to current target +}; + +/** + * @brief Type aliases to simplify user code + */ +typedef _TargetIterator<Target*> TargetIterator; +typedef _TargetIterator<const Target*> ConstTargetIterator; + +//****************************************************************************** +// _TargetIterator::operator++ (postincrement) +//****************************************************************************** + +template<typename T> +_TargetIterator<T> _TargetIterator<T>::operator++(int) +{ + _TargetIterator l_originalIterator(*this); + advance(); + return l_originalIterator; +} + +//****************************************************************************** +// _TargetIterator::operator++ (preincrement) +//****************************************************************************** + +template<typename T> +_TargetIterator<T>& _TargetIterator<T>::operator++() +{ + advance(); + return *this; +} + +#undef TARG_CLASS +#undef TARG_NAMESPACE + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_TARGETITERATOR_H + diff --git a/src/include/usr/targeting/common/pointer.H b/src/include/usr/targeting/common/pointer.H new file mode 100644 index 000000000..f5d919ab6 --- /dev/null +++ b/src/include/usr/targeting/common/pointer.H @@ -0,0 +1,85 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/common/pointer.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_POINTER_H +#define __TARGETING_COMMON_POINTER_H + +/** + * @file targeting/common/pointer.H + * + * @brief Pointer abstraction that allows Hostboot and FSP to use pointers in + * a common way, while maintaining binary compatibility + */ + +#include <builtins.h> + +namespace TARGETING +{ + +/** + * @brief Type (union) which implements a common pointer type between Hostboot + * and FSP + */ +template<typename T> +union AbstractPointer +{ + uint64_t raw; ///< Raw value of the container + struct + { + uint8_t doNotUse[sizeof(uint64_t)-sizeof(void*)]; ///< Do no use + T* ptr; ///< Pointer to instance of type T + }; +}; + +/** + * @brief Macro which accepts an AbstractPointer<T> and returns a pointer + * customized to the platform + * + * @param[in] __PTR__ + * AbstractPointer<T> containing the platform neutral pointer + * + * @return T* pointer customized to the platform + */ +#define TARG_TO_PLAT_PTR(__PTR__) \ + ((__PTR__).ptr) + +/** + * @biref Macro which accepts an AbstractPointer<T>, customizes the pointer to + * the platform, then increments the pointer the specified number of times + * and returns it + * + * @param[in] __PTR__ + * AbstractPointer<T> containing the platform neutral pointer + * + * @param[in] __NUM_INCS__ + * Number of times to increment the platform specific pointer + * + * @return T* pointer customized to the platform, incremented the specified + * number of times + */ +#define TARG_TO_PLAT_PTR_AND_INC(__PTR__,__NUM_INCS__) \ + ((__PTR__).ptr + __NUM_INCS__) + +} // End namespace Targeting + +#endif // __TARGETING_COMMON_POINTER_H diff --git a/src/include/usr/targeting/common/predicates/predicatebase.H b/src/include/usr/targeting/common/predicates/predicatebase.H new file mode 100644 index 000000000..1a12b16a6 --- /dev/null +++ b/src/include/usr/targeting/common/predicates/predicatebase.H @@ -0,0 +1,133 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/predicates/predicatebase.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_PREDICATEBASE_H +#define __TARGETING_COMMON_PREDICATEBASE_H + +/** + * @file targeting/common/predicates/predicatebase.H + * + * @brief Interface for an abstract targeting predicate which filters a set of + * targets based on the programmed criteria. Concrete predicates must + * provide the interface specified here. + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD + +// Other Host Boot Components + +// Targeting Component + +//****************************************************************************** +// Macros +//****************************************************************************** + +/** + * @brief Disable copy constructor / assignment operators + */ +#undef TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS +#define TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS(Type) \ + Type(const Type& i_other); \ + Type& operator=(const Type& i_other) + +/** + * @brief Ensure trace macros are undefined + */ +#undef TARG_NAMESPACE +#undef TARG_CLASS +#undef TARG_FN + +//****************************************************************************** +// Interface +//****************************************************************************** + +namespace TARGETING +{ + +#define TARG_NAMESPACE "TARGETING::" +#define TARG_CLASS "PredicateBase::" + +class Target; + +/** + * @brief Abstract predicate class which specifies an interface for all + * concrete predicates. A predicate acts as a filter on a set of targets. + */ +class PredicateBase +{ + public: + + /** + * @brief Destroys the predicate base class (nothing to do) + */ + virtual ~PredicateBase(); + + /** + * @brief Predicate function call interface + * + * @par Detailed Description: + * This abstract interface must be declared/implemented by all + * derived predicates. A concrete version of this function accepts + * a target, applies the associated predicate logic, and returns + * whether the target met the predicate criteria or not. Caller + * must always supply a valid Target*, or routine will assert. + * + * @param[in] i_pTarget Pointer to target to apply predicate to + * + * @return Boolean indicating whether target matches criteria specified + * by the concrete predicate + * + * @retval true Target matches the predicate criteria + * @retval false Target does not match the predicate criteria + */ + virtual bool operator()( + const Target* i_pTarget) const = 0; + + protected: + + /** + * @brief Create the predicate base class (nothing to do) + * + * @note Constructor protected to allow access from the derived class + */ + PredicateBase() + { + #define TARG_FN "PredicateBase()" + #undef TARG_FN + } + + private: + + TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS(PredicateBase); +}; + +#undef TARG_CLASS +#undef TARG_NAMESPACE + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_PREDICATEBASE_H diff --git a/src/include/usr/targeting/common/predicates/predicatectm.H b/src/include/usr/targeting/common/predicates/predicatectm.H new file mode 100644 index 000000000..de1e5f48f --- /dev/null +++ b/src/include/usr/targeting/common/predicates/predicatectm.H @@ -0,0 +1,189 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/predicates/predicatectm.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_PREDICATECTM_H +#define __TARGETING_COMMON_PREDICATECTM_H + +/** + * @file targeting/common/predicates/predicatectm.H + * + * @brief Interface for a predicate which fiters a target based on its class, + * type, and model. + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD + +// Other Host Boot Components + +// Targeting Component +#include <targeting/common/target.H> +#include <targeting/common/attributes.H> +#include <targeting/common/predicates/predicatebase.H> + +//****************************************************************************** +// Macros +//****************************************************************************** + +#undef TARG_NAMESPACE +#undef TARG_CLASS +#undef TARG_FN + +//****************************************************************************** +// Interface +//****************************************************************************** + +namespace TARGETING +{ + +#define TARG_NAMESPACE "TARGETING::" +#define TARG_CLASS "PredicateCTM::" + +class Target; + +/** + * @brief Predicate class which filters a target based on its class, type, + * and model + */ +class PredicateCTM : public PredicateBase +{ + public: + + /** + * @brief Create a target class, type, model predicate + * + * @param[in] i_class Class of matching target, default NA (any) + * @param[in] i_type Type of matching target, default NA (any) + * @param[in] i_model Model of matching target, default NA (any) + */ + PredicateCTM( + CLASS i_class = CLASS_NA, + TYPE i_type = TYPE_NA, + MODEL i_model = MODEL_NA); + + /** + * @brief Destroy a class, type, model predicate + */ + virtual ~PredicateCTM(); + + /** + * @brief Set the class + * + * @param[in] i_class Class of matching target + */ + void setClass(CLASS i_class); + + /** + * @brief Set the type + * + * @param[in] i_type Type of matching target + */ + void setType(TYPE i_type); + + /** + * @brief Set the model + * + * @param[in] i_model Model of matching target + */ + void setModel(MODEL i_model); + + /** + * @brief Returns whether target matches the specified class, type, + * model + * + * @par Detailed Description: + * Returns whether target matches the specified class, type, model. + * Note that all three fields are always compared, so wildcards + * (CLASS_NA, TYPE_NA, MODEL_NA) must be used for any fields that + * do not matter. See PredicateBase class for parameter/return + * description. + * + * @param[in] i_pTarget + * Target handle pointing to the target to compare to + * + * @return bool indicating whether the target matches or not + */ + virtual bool operator()( + const Target* i_pTarget) const; + + private: + + CLASS iv_class; ///< Class to compare with that of target + TYPE iv_type; ///< Type to compare with that of target + MODEL iv_model; ///< Model to compare with that of target + + TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS(PredicateCTM); +}; + +//****************************************************************************** +// PredicateCTM::PredicateCTM +//****************************************************************************** + +inline PredicateCTM::PredicateCTM( + const CLASS i_class, + const TYPE i_type, + const MODEL i_model) +: iv_class(i_class), + iv_type(i_type), + iv_model(i_model) +{ + #define TARG_FUNC "PredicateCTM(...)" + #undef TARG_FUNC +} + +//****************************************************************************** +// PredicateCTM::setClass +//****************************************************************************** + +inline void PredicateCTM::setClass(CLASS i_class) +{ + iv_class = i_class; +} + +//****************************************************************************** +// PredicateCTM::setType +//****************************************************************************** + +inline void PredicateCTM::setType(TYPE i_type) +{ + iv_type = i_type; +} + +//****************************************************************************** +// PredicateCTM::setModel +//****************************************************************************** + +inline void PredicateCTM::setModel(MODEL i_model) +{ + iv_model = i_model; +} + +#undef TARG_CLASS +#undef TARG_NAMESPACE + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_PREDICATECTM_H diff --git a/src/include/usr/targeting/common/predicates/predicateisfunctional.H b/src/include/usr/targeting/common/predicates/predicateisfunctional.H new file mode 100644 index 000000000..b203ebd41 --- /dev/null +++ b/src/include/usr/targeting/common/predicates/predicateisfunctional.H @@ -0,0 +1,106 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/predicates/predicateisfunctional.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_PREDICATEISFUNCTIONAL_H +#define __TARGETING_COMMON_PREDICATEISFUNCTIONAL_H +/** + * @file targeting/common/predicates/predicateisfunctional.H + * + * PredicateIsFunctional class, used to filter targets for HWP wrapper. + * From the example tutorial page at + * https://w3-connections.ibm.com/wikis/home?lang=en_US#/wiki/Host%20Boot/page/Target%20And%20Attribute%20Usage%20Guide + * : + * Create Custom Predicate + * Take the following predicate "template" and customize to your needs. + * Make sure to: + * 1) Rename the class in the appropriate places + * 2) Implement the operator() function which should return "true" if + * the given Target matches the predicate criteria, false otherwise + * 3) Add any input arguments to the constructor, and any necessary + * private variables to store state + * 4) Implement the destructor, if needed + * 5) Update documentation + * + * See example in src/include/usr/targeting/predicate/predicatectm.H + * (and usr/targeting/predicate/predicatectm.C) + * + */ + + +/******************************************************************************/ +// Includes +/******************************************************************************/ +#include <stdint.h> + +// targeting support. +#include <targeting/common/attributes.H> +#include <targeting/common/entitypath.H> +#include <targeting/common/target.H> +#include <targeting/common/targetservice.H> +#include <targeting/common/iterators/rangefilter.H> +#include <targeting/common/predicates/predicatectm.H> + + +namespace TARGETING +{ + +class PredicateIsFunctional : public PredicateBase +{ + +public: + + /** + * @brief Create a predicate to select targets that + * are marked functional. + * Default (no parms) is to check for functional: assumption is that + * functional implies poweredOn, etc. + * More function will probably be added later. + * + */ + PredicateIsFunctional( ); + + + /** + * @brief Destroy the predicate + */ + virtual ~PredicateIsFunctional(); + + /** + * @brief returns true if target is marked functional + * + * @param[in] i_pTarget + * Handle to the target to perform the predicate check on + * + * @return bool indicating whether target it functional or not + */ + inline bool operator()( + const TARGETING::Target* i_pTarget) const ; + +private: + + TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS(PredicateIsFunctional); +}; + +}; // end namespace + +#endif // __TARGETING_COMMON_PREDICATEISFUNCTIONAL_H diff --git a/src/include/usr/targeting/common/predicates/predicatepostfixexpr.H b/src/include/usr/targeting/common/predicates/predicatepostfixexpr.H new file mode 100644 index 000000000..44fabfb62 --- /dev/null +++ b/src/include/usr/targeting/common/predicates/predicatepostfixexpr.H @@ -0,0 +1,231 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/predicates/predicatepostfixexpr.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_PREDICATEPOSTFIXEXPR_H +#define __TARGETING_COMMON_PREDICATEPOSTFIXEXPR_H + +/** + * @file targeting/common/predicatepostfixexpr.H + * + * @brief Interface for predicate which allows callers to chain multiple other + * predicates together in complex logical expressions, and then evaluate + * them against a target + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <vector> + +// Other Host Boot Components + +// Targeting Component +#include <targeting/common/predicates/predicatebase.H> + +//****************************************************************************** +// Macros +//****************************************************************************** + +#undef TARG_NAMESPACE +#undef TARG_CLASS +#undef TARG_FN + +//****************************************************************************** +// Interface +//****************************************************************************** + +namespace TARGETING +{ + +#define TARG_NAMESPACE "TARGETING::" +#define TARG_CLASS "PredicatePostfixExpr::" + +class Target; + +/** + * @brief Predicate which can compute aribtrarily complex logical expressions + * of other predicates using postfix notation + */ +class PredicatePostfixExpr : public PredicateBase +{ + public: + + /** + * @brief Create empty postfix predicate expression which will always + * evaluate true if not otherwise modified. Any updates to the + * expression completely replace the initial "always true" + * behavior. + */ + PredicatePostfixExpr(); + + /** + * @brief Destroy a postfix predicate expression + * + * @note: Nothing extra to do here since object does not own the + * predicates + */ + virtual ~PredicatePostfixExpr(); + + /** + * @brief Updates the postfix predicate expression by pushing the given + * predicate onto the expression stack + * + * @param[in] i_pPredicate Pointer to existing concrete predicate. + * Passing a NULL predicate is not allowed (results in assert) + * + * @verbatim + * Example: + * + * Stack before calling push(&P2): P1 + * Stack after calling push(&P2): P1 P2 + * @endverbatim + * + * @return Reference to the same predicate expression, for chaining + */ + PredicatePostfixExpr& push( + const PredicateBase* i_pPredicate); + + /** + * @brief Updates the postfix predicate expression by pushing the + * logical "AND" operation onto the expression stack. + * + * @verbatim + * Example: + * + * Stack before calling And(): P1 P2 + * Stack after calling And(): P1 P2 AND + * Stack after evaluation: (P1 && P2) + * @endverbatim + * + * @return Reference to the same predicate expression, for chaining + */ + PredicatePostfixExpr& And(); + + /** + * @brief Updates the postfix predicate expression by pushing the + * logical "NOT" operation onto the expression stack. + * + * @verbatim + * Example: + * + * Stack before calling Not(): P1 + * Stack after calling Not(): P1 NOT + * Stack after evaluation: (!P1) + * @endverbatim + * + * @return Reference to the same predicate expression, for chaining + */ + PredicatePostfixExpr& Not(); + + /** + * @brief Updates the postfix predicate expression by pushing the + * logical "OR" operation onto the expression stack. + * + * @verbatim + * Example: + * + * Stack before calling Or(): P1 P2 + * Stack after calling Or(): P1 P2 OR + * Stack after evaluation: (P1 || P2) + * @endverbatim + * + * @return Reference to the same predicate expression for chaining + */ + PredicatePostfixExpr& Or(); + + /** + * @brief Returns whether the given target matches the criteria + * specified by the postfix predicate expression + * + * @par Detailed Description: + * Returns whether the given target matches the criteria + * specified by the postfix predicate expression. The routine + * sequentially evaluates a predicate against the supplied target + * or applies a logical operation to one or more prior predicate + * evaluations using a postfix algorithm. Routine will assert + * if postfix expression is not formatted properly, final result + * stack does not have exactly one result, target is NULL, or + * invalid logical operator was requested. See PredicateBase class + * for parameter/return description. + * + * @verbatim + * Example: + * + * PredicatePostfixExpr l_expr; + * l_expr.push(&P1).push(&P2).Or().push(&P3).And().Not(); + * + * Equivalent infix expression: !((P1 || P2) && P3) + * Assume predicate results of: P1 = 0, P2 = 1, P3 = 0 + * Expression stack prior to evaluation: P1 P2 OR P3 AND NOT + * Evaluation step 1: 1 P3 AND NOT (evaluated P1 P2 OR) + * Evaluation step 2: 0 NOT (evaluated 1 P3 AND) + * Evaluation step 3: 1 (evaluated 0 NOT; final result) + * @endverbatim + * + * @param[in] i_pTarget + * Handle of the target to evaluate the expression against + * + * @return bool indicating whether the expression is true or no + */ + virtual bool operator()( + const Target* i_pTarget) const; + + private: + + /** + * @brief Enumeration describing the type of logical operator to + * apply to one or more previous predicate evaluations + */ + enum LogicalOperator + { + EVAL, ///< Special logical operator - evaluate a predicate + AND, ///< Logically AND the result of the preceding two evaluations + OR, ///< Logically OR the result of the preceding two evaluations + NOT, ///< Logically negate the result of the preceding evaluation + }; + + /** + * @brief Structure describing one unit of the postfix predicate + * expression under evaluation + */ + struct Operation + { + LogicalOperator logicalOp; ///< Logical operator to + ///< apply to result stack + const PredicateBase* pPredicate; ///< Predicate to evaluate, + ///< if logicalOp == EVAL + }; + + std::vector<Operation> iv_ops; ///< Expression operations to perform + + TARG_DISABLE_COPY_AND_ASSIGNMENT_OPERATORS(PredicatePostfixExpr); +}; + +#undef TARG_CLASS +#undef TARG_NAMESPACE + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_PREDICATEPOSTFIXEXPR_H diff --git a/src/include/usr/targeting/common/predicates/predicates.H b/src/include/usr/targeting/common/predicates/predicates.H new file mode 100644 index 000000000..5a7cf04d9 --- /dev/null +++ b/src/include/usr/targeting/common/predicates/predicates.H @@ -0,0 +1,41 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/predicates/predicates.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_PREDICATES_H +#define __TARGETING_COMMON_PREDICATES_H + +/** + * @file targeting/common/predicates/predicates.H + * + * @brief Shortcut file to pull in all the predicate include files. + * + */ +#include <targeting/common/predicates/predicatebase.H> +#include <targeting/common/predicates/predicatectm.H> +#include <targeting/common/predicates/predicateisfunctional.H> +#include <targeting/common/predicates/predicatepostfixexpr.H> + +// please keep up to date... + +#endif // __TARGETING_COMMON_PREDICATES_H + diff --git a/src/include/usr/targeting/common/target.H b/src/include/usr/targeting/common/target.H new file mode 100644 index 000000000..d91483cad --- /dev/null +++ b/src/include/usr/targeting/common/target.H @@ -0,0 +1,445 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/target.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_TARGET_H +#define __TARGETING_COMMON_TARGET_H + +/** + * @file targeting/common/target.H + * + * @brief Interface for the target class + * + * This header file contains the interface for the target class which + * associates entities of interest to host boot to their various attributes + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <stdint.h> +#include <stdlib.h> +#include <targeting/adapters/assertadapter.H> +#include <targeting/adapters/types.H> +#include <targeting/common/util.H> +#include <targeting/common/pointer.H> +#include <vector> + +// This component +#include <targeting/common/attributes.H> + +namespace TARGETING +{ + +//****************************************************************************** +// Type Aliases +//****************************************************************************** + +class Target; +typedef const Target* ConstTargetHandle_t; +typedef Target* TargetHandle_t; + +typedef std::vector<TargetHandle_t> TargetHandleList; +typedef std::vector<Target> TargetList; + +class Target +{ + public: // Constructors and destructors + + /** + * @brief Destroys the target + * + * Destroys the target, and any exclusively owned resources + * + * @post Target is destroyed, and all exclusively owned resources are + * reclaimed + */ + ~Target(); + + public: // User interface + + /** + * @brief Try to get the target's specified attribute value + * + * Attempts to return the target's specified attribute value. It + * returns false (with invalid o_attrValue) if the specified attribute + * does not exist for the associated target, true (with a valid + * o_attrValue) otherwise. + * + * @param[out] o_attrValue Value of the attribute + * + * @pre Target service must be initialized + * + * @post See "return" + * + * @return bool indicating whether the specified attribute was returned + * or not + * + * @retval true Attribute returned in o_attrValue + * @retval false Attribute not found; o_attValue not valid + */ + template<const ATTRIBUTE_ID A> + inline bool tryGetAttr( + typename AttributeTraits<A>::Type& o_attrValue) const + { + // Note: the compiler optimizes the following check (which fails + // at compile time if the attribute is not readable) away + if(AttributeTraits<A>::readable) { } + if(AttributeTraits<A>::notHbMutex) { } + return _tryGetAttr(A,sizeof(o_attrValue),&o_attrValue); + } + + /** + * @brief Get the target's specified attribute value + * + * Returns the target's specified attribute value. If the specified + * attribute does not exist for the associated target, the routine + * asserts. Thus callers must be sure the attribute exists for the + * given target. + * + * @pre Target service must be initialized + * + * @post Target's specified attribute value returned, or assert + * called if specified attribute doesn't exist for the + * associated target + * + * @return Data type associated with the attribute being returned + * + * @retval Varies The attribute data + */ + template<const ATTRIBUTE_ID A> + typename AttributeTraits<A>::Type getAttr() const; + + /** + * @brief DEBUG ONLY! Returns the requested attribute as a string + * + * Returns the attribute value (for the associated target) as a string. + * If the specified attribute does not have a string conversion, the + * compile will fail. + * + * @pre Target service must be initialized + * + * @post Specified attribute's value returned as a string. If the + * specified attribute does not exist, the routine asserts. + * + * @return String representing the attribute + * + * @retval Varies based on the attribute type and value + */ + template<const ATTRIBUTE_ID A> + const char* getAttrAsString() const; + + /** + * @brief Tries to set the target's specified attribute value + * + * Attempts to set the target's specified attribute value. It + * returns false if the specified attribute does not exist for the + * associated target, true otherwise. + * + * @param[in] i_attrValue Value of the attribute + * + * @pre Target service must be initialized + * + * @post Target's attribute value updated (if it exists), and caller + * notified whether the update occurred or not. + * + * @return bool indicating whether the specified attribute was updated + * or not + * + * @retval true Attribute updated + * @retval false Attribute not updated + */ + template<const ATTRIBUTE_ID A> + bool trySetAttr( + typename AttributeTraits<A>::Type const& i_attrValue) + { + // Note: the compiler optimizes the following check (which fails + // at compile time if the attribute is not writable) away + if(AttributeTraits<A>::writeable) { } + if(AttributeTraits<A>::notHbMutex) { } + return _trySetAttr(A,sizeof(i_attrValue),&i_attrValue); + } + + /** + * @brief Returns pointer to a mutex attribute associated with the + * target + * + * @pre Target service must be initialized and the mutex attribute + * must exist + * + * @post See brief section + * + * @return Pointer to the specified mutex attribute + */ + template<const ATTRIBUTE_ID A> + mutex_t* getHbMutexAttr() const; + + /** + * @brief Returns pointer to a mutex attribute associated with the + * target, if it exists + * + * @param[out] o_pMutex Reference to a mutex pointer, which will be + * updated with the address of the mutex attribute if it exists + * (ignored otherwise) + * + * @pre Target service must be initialized + * + * @post See brief section + * + * @return bool indicating whether the attribute was found or not + * + * @retval true Attribute was found (and returned) + * @retval false Attribute was not found, o_pMutex was not updated + */ + template<const ATTRIBUTE_ID A> + bool tryGetHbMutexAttr( + mutex_t*& o_pMutex) const; + + /** + * @brief Sets the target's specified attribute value + * + * Sets the target's specified attribute value. + * + * @param[in] i_attrValue Value of the attribute + * + * @pre Target service must be initialized + * + * @post Target's attribute value updated if it exists, otherwise + * routine asserts + */ + template<const ATTRIBUTE_ID A> + void setAttr( + typename AttributeTraits<A>::Type const& i_attrValue) + { + bool l_wrote = trySetAttr<A>(i_attrValue); + + //@TODO: Remove assert once release has stabilized + TARG_ASSERT(l_wrote,"TARGETING::Target::setAttr<%d>: trySetAttr " + "returned false",A); + } + + /** + * @brief Perform FFDC for the target instance + * + * @param[out] io_size + * number of bytes of buffer filled with FFDC + * + * @return pointer to dynamically allocated FFDC buffer + * + * @post caller must call free() to release the buffer + */ + char * targetFFDC( uint32_t & o_size ) const; + + private: // Private helper interfaces + + /** + * @brief Tries to get the target's specified attribute value + * + * Tries to get the target's specified attribute value + * + * @param[in] i_attr Attribute to retrieve + * @param[in] i_size Size of the attribute + * @param[in/out] io_attrData On input, location to store the attribute + * On output, location updated with attribute data + * + * @pre Target service must be initialized + * + * @post Caller notified if attribute retrieval succeeded or not. If + * so, the attribute data is stored at io_addrData + * + * @return bool indicating if attribute retrieval succeeded or not + * + * @retval true Attribute retrieval succeeded + * @retval false Attribute retrieval failed + */ + bool _tryGetAttr( + ATTRIBUTE_ID i_attr, + uint32_t i_size, + void* io_attrData) const; + + /** + * @brief Tries to set the target's specified attribute value + * + * Tries to set the target's specified attribute value + * + * @param[in] i_attr Attribute to retrieve + * @param[in] i_size Size of the attribute + * @param[in] i_pAttrData Location holding the attribute data to set + * + * @pre Target service must be initialized + * + * @post If attribute exists for the associated target, attribute value + * updated and success (true) returned. Otherwise, attribute value + * not updated and failure (false) returned. + * + * @return bool indicating if attribute update succeeded or not + * + * @retval true Attribute update succeeded + * @retval false Attribute update failed + */ + bool _trySetAttr( + ATTRIBUTE_ID i_attr, + uint32_t i_size, + const void* i_pAttrData) const; + + /** + * @brief Gets a pointer to the target's associated attribute + * + * Gets a pointer to the target's associated attribute + * + * @param[in] i_attr Attribute to retrieve + * @param[out] o_pAttr Pointer to data location to hold the attribute + * data + * + * @pre Target service must be initialized + * + * @post If attribute exists for the associated target, caller's + * pointer updated with associated attribute pointer. Otherwise, + * caller's pointer updated to NULL. + */ + void _getAttrPtr( + ATTRIBUTE_ID i_attr, + void*& o_pAttr) const; + + /** + * @brief Returns pointer to a mutex attribute associated with the + * target + * + * @param[in] i_attribute Mutex attribute to return + * + * @pre Target service must be initialized and the mutex attribute + * must exist + * + * @post See brief section + * + * @return Pointer to the specified mutex attribute + */ + mutex_t* _getHbMutexAttr( + const ATTRIBUTE_ID i_attribute) const; + + /** + * @brief Returns pointer to a mutex attribute associated with the + * target, if it exists + * + * @param[in] i_attribute Mutex attribute to return + * @param[out] o_pMutex Reference to a mutex pointer, which will be + * updated with the address of the mutex attribute if it exists + * (ignored otherwise) + * + * @pre Target service must be initialized + * + * @post See brief section + * + * @return bool indicating whether the attribute was found or not + * + * @retval true Attribute was found (and returned) + * @retval false Attribute was not found, o_pMutex was not updated + */ + bool _tryGetHbMutexAttr( + const ATTRIBUTE_ID i_attribute, + mutex_t*& o_pMutex) const; + + private: // Private instance variables + + uint32_t iv_attrs; ///< Total attributes allowed for this + ///< instance + + // Pointer to array of valid attributes + TARGETING::AbstractPointer<ATTRIBUTE_ID> iv_pAttrNames; + + // Pointer to array of void* (which point to attributes) + TARGETING::AbstractPointer< AbstractPointer<void> > iv_pAttrValues; + + private: // Private CTORs/DTORs/Operators + + /** + * @brief Build a target object + * + * Builds a target object; currently there is little to no need to + * construct new targets; they are already preloaded in PNOR. + */ + Target(); + + // Disable the copy constructor/assignment operator. + + Target( + const Target& i_right); + + Target& operator=( + const Target& i_right); + + friend class PnorBuilderService; + +} PACKED; + +template<const ATTRIBUTE_ID A> +typename AttributeTraits<A>::Type Target::getAttr() const +{ + typename AttributeTraits<A>::Type l_attrValue; + bool l_read = tryGetAttr<A>(l_attrValue); + + //@TODO Remove assert once release has stablized + TARG_ASSERT(l_read,"TARGETING::Target::getAttr<%d>: tryGetAttr " + "returned false",A); + return l_attrValue; +} + +template<const ATTRIBUTE_ID A> +mutex_t* Target::getHbMutexAttr() const +{ + if(AttributeTraits<A>::hbMutex) { } + if(AttributeTraits<A>::readable) { } + if(AttributeTraits<A>::writeable) { } + return _getHbMutexAttr(A); +} + +template<const ATTRIBUTE_ID A> +bool Target::tryGetHbMutexAttr( + mutex_t*& o_pMutex) const +{ + if(AttributeTraits<A>::hbMutex) { } + if(AttributeTraits<A>::readable) { } + if(AttributeTraits<A>::writeable) { } + return _tryGetHbMutexAttr(A,o_pMutex); +} + +template<const ATTRIBUTE_ID A> +const char* Target::getAttrAsString() const +{ + // Note: the compiler optimizes the following check (which fails + // at compile time if the attribute does not have a string + // conversion) away + if(AttributeTraits<A>::hasStringConversion) { } + typename AttributeTraits<A>::Type l_attrValue; + bool l_read = tryGetAttr<A>(l_attrValue); + + //@TODO Remove assert once release has stabilized + TARG_ASSERT(l_read,"TARGETING::Target::getAttrAsString<%d>: tryGetAttr " + "returned false",A); + return attrToString<A>(l_attrValue); +} + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_TARGET_H diff --git a/src/include/usr/targeting/common/targetservice.H b/src/include/usr/targeting/common/targetservice.H new file mode 100644 index 000000000..444dbc472 --- /dev/null +++ b/src/include/usr/targeting/common/targetservice.H @@ -0,0 +1,558 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/targetservice.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_TARGETSERVICE_H +#define __TARGETING_COMMON_TARGETSERVICE_H + +/** + * @file targeting/common/targetservice.H + * + * @brief Interface for the target service + * + * This header file contains the interface definition for the target service + * which is responsible for configuring and aggregating the pool of valid + * targets, and providing services to access targets based on various criteria + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// STD +#include <stdint.h> +#include <stdlib.h> +#include <vector> + +// This component +#include <targeting/common/attributes.H> +#include <targeting/common/iterators/iterators.H> +#include <targeting/common/predicates/predicates.H> +#include <targeting/adapters/types.H> + +//****************************************************************************** +// Interface Definitions +//****************************************************************************** + +//****************************************************************************** +// Method to access the targeting service externally +//****************************************************************************** + +namespace TARGETING +{ + class TargetService; + + /** + * @brief Returns a reference to the targeting service singleton + * + * @return Reference to the targeting service + */ + TARGETING::TargetService& targetService(); + +/** + * @brief Sentinel representing the master processor chip target early in + * host boot prior to initialization of the target service. Needed by the + * DD framework to bring PNOR device driver online. Note this target + * cannot be used as input to any target service APIs. + */ +static Target* const MASTER_PROCESSOR_CHIP_TARGET_SENTINEL + = (sizeof(void*) == 4) ? + reinterpret_cast<TARGETING::Target* const>(0xFFFFFFFF) + : reinterpret_cast<TARGETING::Target* const>(0xFFFFFFFFFFFFFFFFULL); + +/** + * @brief TargetService class + * + * This class manages the set of possible targets and provides facility to + * access specific targets, based on given criteria + */ +class TargetService +{ + public: + + /** + * @brief Enum specifying the recursion depth for target searching + * + * Indicates whether to return only IMMEDIATE children/parent of a + * target, or ALL children/parents of a target + */ + enum RECURSION_LEVEL + { + IMMEDIATE = 0x01, ///< Return immediate children/parent of a target + ALL = 0x02, ///< Return all children/parents of a target + }; + + /** + * @brief Enum specifying the type of association between targets + * + * Indicates what relationship the result target should have to the + * target in question + */ + enum ASSOCIATION_TYPE + { + PARENT, ///< The result target(s) should be parents by + ///< containment + CHILD, ///< The result target(s) should be children by + ///< containment + PARENT_BY_AFFINITY, ///< The result target(s) should be the parents + ///< by hardware affinity + CHILD_BY_AFFINITY, ///< The result target(s) should be children by + ///< Hardware affinity. For example the child + ///< of a memory controller channel target might + ///< be a DIMM target + VOLTAGE_SUPPLIER, ///< The result target(s) should be the voltage + ///< supplier + VOLTAGE_CONSUMER, ///< The result target(s) should be the voltage + ///< consumer + }; + + public: + + /** + * @brief Construct the target service + * + * Constructs the target service, but does not actually initialize the + * target pool + * + * @post Target service instantiated, but target pool not initialized + */ + TargetService(); + + /** + * @brief Destroys the target service + * + * Destroys the target service; it should never be run since it hides + * behind a singleton, but is included for completeness + * + * @post Target service is destroyed, and all owned resources are + * reclaimed + */ + ~TargetService(); + + /** + * @brief Initializes the target service + * + * Initializes the target service, including determining maximum number + * of targets, setting up the target pool, etc. Should be called + * once PNOR is accessible can be mapped + * + * @pre N/A + * + * @post Target service fully initialized with all possible targets + */ + void init(); + + /** + * @brief Returns whether target service has initialized or not + * + * @return bool indicating whether service has initialized or not + * @retval true Service has initialized and can be used + * @retval false Service has not initializated and should not be used + * (other than to run the initialization) + */ + bool isInitialized() const + { + return iv_initialized; + } + + /** + * @brief Map iterator types to common aliases + */ + typedef TargetIterator iterator; + typedef ConstTargetIterator const_iterator; + + /** + * @brief Return iterator which points to first target service target + * (or end() if none) + * + * @return Iterator pointing to first target service target + */ + iterator begin(); + + /** + * @brief Return iterator to const which points to first target service + * target (or end() if none) + * + * @return Iterator to const pointing to first target service target + */ + const_iterator begin() const; + + /** + * @brief Return iterator which points to the "past the end of the + * list" target maintained by the target service + * + * @return Iterator pointing to the "past the end of the list" target + * maintained by the target service + */ + iterator end(); + + /** + * @brief Return iterator to const which points to the "past the end of + * the list" target maintained by the target service + * + * @return Iterator to const pointing to the "past the end of the list" + * target maintained by the target service + */ + const_iterator end() const; + + /** + * @brief Allow iterator access to the target service's target store + */ + friend class _TargetIterator<Target*>; + friend class _TargetIterator<const Target*>; + + /** + * @brief Returns the top level physical target + * + * Returns the top level (usually system) target. Caller must check + * for a NULL top level target + * + * @param[out] o_targetHandle Top level target handle + * + * @pre N/A + * + * @post The returned handle is NULL if a top level target doesn't + * exist or service not initialized, otherwise it references a + * valid top level target + */ + void getTopLevelTarget( + Target*& o_targetHandle) const; + + /** + * @brief Returns whether specified entity path corresponds to a real + * target + * + * Consults the specified entity path and searches through all + * available targets to find a matching entity path attribute. If it + * finds a match, then the associated target exists, otherwise it does + * not exist + * + * @param[in] i_entityPath Entity path to verify for existence + * @param[out] o_exists Whether the entity path corresponds to a + * target + * + * @pre N/A + * + * @post "true" returned to caller if specified entity path exists, + * "false" if not or service not initialized + */ + void exists( + const EntityPath& i_entityPath, + bool& o_exists) const; + + /** + * @brief Returns a target handle which has an associated entity path + * matching the specified entity path + * + * Returns a target handle which has an associated entity path + * matching the specified entity path. Caller must check the + * returned handle for NULL. + * + * @param[in] i_entityPath Entity path for which to find the matching + * target handle + * + * @pre N/A + * + * @post NULL returned to caller if no match was found or service + * not initialized, otherwise a valid handle returned + * + * @return Target handle + * + * @retval NULL No target match found + * @retval !NULL Handle to the corresponding target + */ + Target* toTarget( + const EntityPath& i_entityPath) const; + + /** + * @brief Returns the master processor chip target handle + * + * Returns the master processor chip target handle. On systems + * without an alternate master, it returns a handle to the only master, + * if found (NULL otherwise). On systems with multiple potential + * masters, it returns a target handle to the acting master (NULL + * otherwise). If targeting information is not yet accessible (very + * early in the host boot IPL), the returned target handle will be a + * sentinel value representing the master (whichever it may be) + * + * @param[out] o_masterProcChipTarget Target handle referring to the + * current master processor chip (the one connected to PNOR) + * + * @pre None + * + * @post Master processor chip targets returned or a dummy value + * representing the acting master processor chip if the targeting + * information is not yet initialized + */ + void masterProcChipTargetHandle( + Target*& o_masterProcChipTargetHandle) const; + + /** + * @brief Returns whether the specified entity path attribute exists + * for a specified target, and if so, the value of that attribute + * + * Returns whether the specified entity path attribute exists for a + * specified target, and if so, the value of that attribute. If the + * target doesn't exist, or the attribute doesn't correspond to an + * entity path attribute, or the entity path attribute doesn't exist + * for the target, then the routine returns false and the entity path + * value is invalid. + * + * @param[in] i_attr Entity path attribute to read + * @param[in] i_pTarget Target handle to read the attribute from + * @param[out] o_entityPath Value of the target's associated entity + * path value + * + * @pre N/A + * + * @post See "return" + * + * @return bool indicating whether the specified attribute exists + * for the specified target and whether the returned entity path + * value is valid + * + * @retval true Specified attribute exists, entity path is valid + * @retval false Specified attribute does not exist, entity path is + * invalid + */ + bool tryGetPath( + ATTRIBUTE_ID i_attr, + const Target* i_pTarget, + EntityPath& o_entityPath) const; + + /** + * @brief Returns entity paths of targets associated to the specified + * target in a specific way + * + * Returns entity paths of targets associated to the specified target, + * as indicated by an association type. Based on the specified + * recursion level, the routine will determine the immediate + * associations, or all possible associations. For example, if caller + * supplies a processor chip target and asks for its children targets, + * the routine will return the next set of targets in the physical + * hierarchy. Conversely if the caller asks for ALL children targets + * for said source target, the routine will return all targets + * contained within the processor chip. + * + * @param[out] o_list List of target handles that match the specified + * criteria + * @param[in] i_pTarget Target from which to search for other targets + * @param[in] i_type Type of association linking the specified target + * to candidate result targets + * @param[in] i_recursionLevel Whether to return candidate targets + * immediately associated to the specified target or recursively + * associated to it. + * @param[in] i_pPredicate Pointer to a predicate to be evaluated + * against each candidate target (as determined by the source + * target, type, and recursion level parameters). If the predicate + * returns true, the target will be added to the result list. A + * value of NULL acts as a predicate that always returns true. + * + * @pre N/A + * + * @post Caller's list cleared; list of target handles matching the + * specified criteria returned + */ + void getAssociated( + TargetHandleList& o_list, + const Target* const i_pTarget, + const ASSOCIATION_TYPE i_type = CHILD, + const RECURSION_LEVEL i_recursionLevel = IMMEDIATE, + const PredicateBase* i_pPredicate = NULL) const; + + /** + * @brief Dump the target service for debug only + * + * @post Output written to buffer + */ + void dump() const; + + private: + + /** + * @brief Enum specifying which direction to traverse associations + * between targets + * + * Given a general class of association between targets, this enum + * tells the target service which direction to search along an entity + * path for the result targets + */ + enum ASSOCIATION_DIRECTION + { + INWARDS, ///< Search for associated targets of the specified target + ///< that happen to be closer to the top level target + OUTWARDS, ///< Search for associated targets of the specified target + ///< that happen to be farther from the top level target + }; + + /** + * @brief Structure mapping an association type to an entity path + * attribute and entity path search direction + * + * This map allows the target service to accept an association type + * from a caller and determine the appropriate entity path to search + * along for the result target, and in which direction along the path + */ + struct AssociationAttrMap + { + ASSOCIATION_TYPE associationType; ///< Specifies the type of + ///< association to traverse + ASSOCIATION_DIRECTION associationDir; ///< Specifies which + ///< direction along an + ///< entity path to search + ATTRIBUTE_ID attr; ///< Specifies which entity + ///< path to search along + }; + + /** + * @brief Aliases a vector of association mappings + */ + typedef std::vector< AssociationAttrMap > AssociationMappings_t; + + /** + * @brief Configures the pool of targets + * + * This function computes the maximum number of targets possible based + * on the PNOR (or override) image, and updates the target service to + * point to the start of the target array, wherever it may reside + * + * @pre Target service must not be initialized + * + * @post Target service target pool configured for access + */ + void _configureTargetPool(); + + /** + * @brief Computes the maximum number of targets, caches the value + * and returns it to the caller + * + * Computes the maximum number of targets possible based on the PNOR + * (or override) image and returns it to the caller + * + * @pre Target service must not already be initialized + * + * @post Target service updated with maximum target count. Count also + * returned to caller + * + * @return uint32_t indicating the maximum number of targets possible + */ + uint32_t _maxTargets(); + + /** + * @brief Returns handles to the targets associated to the + * target represented by the specified entity path such that the + * results are closer to the top level target than the source + * + * Returns handles to the targets associated to the target represented + * by the specified entity path such that the results are closer to the + * top level target than the source. An IMMEDIATE recursion level + * returns handles to targets that are one association away from the + * target referenced by the supplied entity path. A recursion level of + * ALL recursively returns results. + * + * @param[in] i_attr Entity path attribute that is used as the basis + * for lookups on candidate targets + * @param[in] i_recursionLevel Whether to provide immediate or + * recursive results + * @param[in] i_entityPath Entity path to start search from + * @param[in] i_pPredicate Pointer to a predicate to be evaluated + * against each candidate target. If the predicate returns true, + * the target will be added to the result list. A value of NULL + * acts as a predicate that always returns true. + * @param[out] o_list List of returned target handles + * + * @pre Target service must be initialized + * + * @post List of target handles corresponding to targets closer to the + * top level target than the one referenced by the specified entity + * path returned + */ + void _getInwards( + ATTRIBUTE_ID i_attr, + RECURSION_LEVEL i_recursionLevel, + EntityPath i_entityPath, + const PredicateBase* i_pPredicate, + TargetHandleList& o_list) const; + + /** + * @brief Returns handles to the targets associated to the + * target represented by the specified entity path such that the + * results are farther from the top level target than the source + * + * Returns handles to the targets associated to the target represented + * by the specified entity path such that the results are farther from + * the top level target than the source. An IMMEDIATE recursion level + * returns handles to targets that are one association away from the + * target referenced by the supplied entity path. A recursion level of + * ALL recursively returns results. + * + * @param[in] i_attr Entity path attribute that is used as the basis + * for lookups on candidate targets + * @param[in] i_recursionLevel Whether to provide immediate or + * recursive results + * @param[in] i_entityPath Entity path to look from + * @param[in] i_pPredicate Pointer to a predicate to be evaluated + * against each candidate target. If the predicate returns true, + * the target will be added to the result list. A value of NULL + * acts as a predicate that always returns true. + * @param[out] o_list List of returned target handles + * + * @pre Target service must be initialized + * + * @post List of target handles corresponding to targets farther from + * the top level target than the one referenced by the specified + * entity path returned. + */ + void _getOutwards( + ATTRIBUTE_ID i_attr, + RECURSION_LEVEL i_recursionLevel, + EntityPath i_entityPath, + const PredicateBase* i_pPredicate, + TargetHandleList& o_list ) const; + + // Instance variables + bool iv_initialized; ///< Is service initialized or not + Target (*iv_targets)[]; ///< Pointer to array of target objects + uint32_t iv_maxTargets; ///< Maximum # target objects in the array + const void* iv_pPnor; ///< Pointer to the PNOR targeting section + AssociationMappings_t iv_associationMappings; ///< Association map + + // Disable copy constructor / assignment operator + + TargetService( + const TargetService& i_right); + + TargetService& operator=( + const TargetService& i_right); +}; + +/** + * @brief Singleton to access the only TargetService; deemphasized + * intentionally + */ +class TargetService; + +TARG_DECLARE_SINGLETON(TARGETING::TargetService,theTargetService); + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_TARGETSERVICE_H diff --git a/src/include/usr/targeting/common/targreasoncodes.H b/src/include/usr/targeting/common/targreasoncodes.H new file mode 100644 index 000000000..8214c1f0b --- /dev/null +++ b/src/include/usr/targeting/common/targreasoncodes.H @@ -0,0 +1,54 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/targreasoncodes.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END +#ifndef __TARGETING_COMMON_TARGREASONCODES_H +#define __TARGETING_COMMON_TARGREASONCODES_H + +/** + * @file targeting/common/targetreasoncodes.H + * + * @brief Provides reason codes for various targeting errors + */ + +#include <targeting/adapters/types.H> + +namespace TARGETING +{ + +enum TargetingModuleId +{ + TARG_MOD_TEST = 0x01, + TARG_MOD_ATTRRP = 0x02, +}; + +enum TargetingReasonCode +{ + TARG_RC_TEST_TARGET_FFDC = TARG_COMP_ID | 0x01, + TARG_RC_BAD_EYECATCH = TARG_COMP_ID | 0x02, + TARG_RC_MM_BLOCK_FAIL = TARG_COMP_ID | 0x03, + TARG_RC_MM_PERM_FAIL = TARG_COMP_ID | 0x04, + TARG_RC_ATTR_MSG_FAIL = TARG_COMP_ID | 0x05, +}; + +}; // End TARGETING namespace + +#endif // __TARGETING_COMMON_TARGREASONCODES_H diff --git a/src/include/usr/targeting/common/trace.H b/src/include/usr/targeting/common/trace.H new file mode 100644 index 000000000..c298eb9ab --- /dev/null +++ b/src/include/usr/targeting/common/trace.H @@ -0,0 +1,65 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/usr/targeting/trace.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2011 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_TRACE_H +#define __TARGETING_COMMON_TRACE_H + +/** + * @file targeting/common/trace.H + * + * @brief Targeting related trace macros. Callers of these macros must + * define TARG_NAMESPACE, TARG_CLASS, and TARG_FN as appropriate + */ + +//****************************************************************************** +// Includes +//****************************************************************************** + +// Other includes +#include <targeting/adapters/traceadapter.H> + +#define TARG_LOC TARG_NAMESPACE TARG_CLASS TARG_FN ": " + +#define TARG_ERR_LOC ERR_MRK " " TARG_LOC + +#define TARG_TAG "[TARG]" +#define TARG_ENTER(args...) \ + TRACFCOMP(TARGETING::g_trac_targeting,TARG_TAG " " \ + ENTER_MRK " " TARG_NAMESPACE \ + TARG_CLASS TARG_FN " " args) + +#define TARG_EXIT(args...) \ + TRACFCOMP(TARGETING::g_trac_targeting,TARG_TAG " " \ + EXIT_MRK " " TARG_NAMESPACE \ + TARG_CLASS TARG_FN " " args) + +#define TARG_ERR(args...) \ + TRACFCOMP(TARGETING::g_trac_targeting,TARG_TAG " " ERR_MRK " " args) + +#define TARG_INF(args...) \ + TRACFCOMP(TARGETING::g_trac_targeting,TARG_TAG " " INFO_MRK " " args) + +#define TARG_BIN(args...) \ + TRACFBIN(TARGETING::g_trac_targeting,TARG_TAG " " args) + +#endif // __TARGETING_COMMON_TRACE_H diff --git a/src/include/usr/targeting/common/util.H b/src/include/usr/targeting/common/util.H new file mode 100644 index 000000000..4851dd87b --- /dev/null +++ b/src/include/usr/targeting/common/util.H @@ -0,0 +1,72 @@ +// IBM_PROLOG_BEGIN_TAG +// This is an automatically generated prolog. +// +// $Source: src/include/usr/targeting/util.H $ +// +// IBM CONFIDENTIAL +// +// COPYRIGHT International Business Machines Corp. 2012 +// +// p1 +// +// Object Code Only (OCO) source materials +// Licensed Internal Code Source Materials +// IBM HostBoot Licensed Internal Code +// +// The source code for this program is not published or other- +// wise divested of its trade secrets, irrespective of what has +// been deposited with the U.S. Copyright Office. +// +// Origin: 30 +// +// IBM_PROLOG_END + +#ifndef __TARGETING_COMMON_UTIL_H +#define __TARGETING_COMMON_UTIL_H + +/** + * @file targeting/common/util.H + * + * @brief Targeting utility functions + */ + +namespace TARGETING +{ + +class Target; + +/** + * @brief Macro which indicates whether to translate addresses or not + * + * @par Detailed Description: + * If PPC platform (FSP or Hostboot), if 8 byte pointers then it's + * Hostboot, so don't translate. If 4 byte pointers then it's FSP so + * translate. If !PPC (x86 32 or 64 bit), then always translate + * + * @note List of preprocessor macros defined can be determined by calling: + * ppc64-mcp6-gcc -dM -E - < /dev/null + */ +#ifdef __PPC__ +#define TARG_ADDR_TRANSLATION_REQUIRED (sizeof(void*)==4) +#else +#define TARG_ADDR_TRANSLATION_REQUIRED (1) +#endif + +/** + * @brief Checks to see if we are running in a hardware simulation + * environment, i.e. VPO/VBU (not Simics) + * + * @return true if in VPO/VBU + */ +bool is_vpo( void ); + +/** + * @brief Safely fetch the HUID of a Target + * @param[in] Pointer to a Target + * @return HUID of Target, Zero if NULL, 0xFFFFFFFF if Sentinel + */ +uint32_t get_huid( const Target* i_target ); + +} + +#endif // __TARGETING_COMMON_UTIL_H |
