diff options
Diffstat (limited to 'src/include/usr/targeting/common/targetservice.H')
| -rw-r--r-- | src/include/usr/targeting/common/targetservice.H | 558 |
1 files changed, 558 insertions, 0 deletions
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 |
