From 4157b5631a1bbfcc7f9f95480b54e9ade7abce7d Mon Sep 17 00:00:00 2001 From: Nick Bofferding Date: Tue, 17 Apr 2012 22:30:59 -0500 Subject: Support targeting code commonality - Moved common targeting code to own subtrees - Updated many components with header file changes - Implemented abstract pointer class - Implemented Hostboot specific support for targeting commonality - Changed attribute VMM base address to 4 GB (From 3 GB) - Removed tabs, fixed > 80 character lines Change-Id: Ie5a6956670bfa4f262f7691b4f0ce5a20ed289fe RTC: 35569 Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/909 Tested-by: Jenkins Server Reviewed-by: A. Patrick Williams III --- src/include/usr/targeting/common/target.H | 445 ++++++++++++++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 src/include/usr/targeting/common/target.H (limited to 'src/include/usr/targeting/common/target.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 +#include +#include +#include +#include +#include +#include + +// This component +#include + +namespace TARGETING +{ + +//****************************************************************************** +// Type Aliases +//****************************************************************************** + +class Target; +typedef const Target* ConstTargetHandle_t; +typedef Target* TargetHandle_t; + +typedef std::vector TargetHandleList; +typedef std::vector 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 + inline bool tryGetAttr( + typename AttributeTraits::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::readable) { } + if(AttributeTraits::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 + typename AttributeTraits::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 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 + bool trySetAttr( + typename AttributeTraits::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::writeable) { } + if(AttributeTraits::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 + 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 + 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 + void setAttr( + typename AttributeTraits::Type const& i_attrValue) + { + bool l_wrote = trySetAttr(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 iv_pAttrNames; + + // Pointer to array of void* (which point to attributes) + TARGETING::AbstractPointer< AbstractPointer > 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 +typename AttributeTraits::Type Target::getAttr() const +{ + typename AttributeTraits::Type l_attrValue; + bool l_read = tryGetAttr(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 +mutex_t* Target::getHbMutexAttr() const +{ + if(AttributeTraits::hbMutex) { } + if(AttributeTraits::readable) { } + if(AttributeTraits::writeable) { } + return _getHbMutexAttr(A); +} + +template +bool Target::tryGetHbMutexAttr( + mutex_t*& o_pMutex) const +{ + if(AttributeTraits::hbMutex) { } + if(AttributeTraits::readable) { } + if(AttributeTraits::writeable) { } + return _tryGetHbMutexAttr(A,o_pMutex); +} + +template +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::hasStringConversion) { } + typename AttributeTraits::Type l_attrValue; + bool l_read = tryGetAttr(l_attrValue); + + //@TODO Remove assert once release has stabilized + TARG_ASSERT(l_read,"TARGETING::Target::getAttrAsString<%d>: tryGetAttr " + "returned false",A); + return attrToString(l_attrValue); +} + +} // End namespace TARGETING + +#endif // __TARGETING_COMMON_TARGET_H -- cgit v1.2.1