From e93bda2d2a30ff9959384dce0563ab143bc30aad Mon Sep 17 00:00:00 2001 From: Thi Tran Date: Tue, 28 Jun 2011 11:17:12 -0500 Subject: Initial HWPF delivery Update after pass-around review Change-Id: I8f81dd7820b61607e9a98d17c81e74fface42c54 Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/160 Tested-by: Jenkins Server Reviewed-by: A. Patrick Williams III --- src/include/usr/hwpf/fapi/fapi.H | 22 ++ src/include/usr/hwpf/fapi/fapiAttributeService.H | 426 ++++++++++++++++++++++ src/include/usr/hwpf/fapi/fapiHwAccess.H | 115 ++++++ src/include/usr/hwpf/fapi/fapiReturnCode.H | 174 +++++++++ src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H | 106 ++++++ src/include/usr/hwpf/fapi/fapiReturnCodes.H | 39 ++ src/include/usr/hwpf/fapi/fapiSystemConfig.H | 73 ++++ src/include/usr/hwpf/fapi/fapiTarget.H | 195 ++++++++++ src/include/usr/hwpf/fapi/fapiUtil.H | 28 ++ 9 files changed, 1178 insertions(+) create mode 100644 src/include/usr/hwpf/fapi/fapi.H create mode 100644 src/include/usr/hwpf/fapi/fapiAttributeService.H create mode 100644 src/include/usr/hwpf/fapi/fapiHwAccess.H create mode 100644 src/include/usr/hwpf/fapi/fapiReturnCode.H create mode 100644 src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H create mode 100644 src/include/usr/hwpf/fapi/fapiReturnCodes.H create mode 100644 src/include/usr/hwpf/fapi/fapiSystemConfig.H create mode 100644 src/include/usr/hwpf/fapi/fapiTarget.H create mode 100644 src/include/usr/hwpf/fapi/fapiUtil.H (limited to 'src/include/usr/hwpf/fapi') diff --git a/src/include/usr/hwpf/fapi/fapi.H b/src/include/usr/hwpf/fapi/fapi.H new file mode 100644 index 000000000..cc2066990 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapi.H @@ -0,0 +1,22 @@ +/** + * @file fapi.H + * + * @brief Includes all the header files necessary for the FAPI interface. + */ + +#ifndef FAPI_H_ +#define FAPI_H_ + +#include +#include +#include +#include +#include +#include +#include +#include +#include // Generated file +#include // Generated file +#include + +#endif // FAPI_H_ diff --git a/src/include/usr/hwpf/fapi/fapiAttributeService.H b/src/include/usr/hwpf/fapi/fapiAttributeService.H new file mode 100644 index 000000000..52981318a --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiAttributeService.H @@ -0,0 +1,426 @@ +/** + * @file fapiAttributeService.H + * + * @brief Defines the FAPI_ATTR_GET and FAPI_ATTR_SET macros that a user calls + * to get/set attributes and the AttributeService functions that the + * macros use to get/set attributes + */ + +#ifndef FAPIATTRIBUTESERVICE_H_ +#define FAPIATTRIBUTESERVICE_H_ +#include +#include +#include +#include + +/** + * @brief Macros called by user to get/set attributes + * + * @note The user must use these macros rather than use the AttributeService + * _get/_set functions so that the type can be checked at compile time + * + * Code must have a pointer to a Target and an attribute ID (from XML file): + * fapi::ReturnCode l_rc; + * fapi::Target * l_pTarget = ????; + * AttributeId l_id = ????; + * + * To get a copy of a string attribute + * char * l_pString = NULL; + * l_rc = FAPI_ATTR_GET(l_id, l_pTarget, l_pString); + * delete[] l_pString; // When finished with the attribute + * + * To set a string attribute + * l_rc = FAPI_ATTR_SET(l_id, l_pTarget, "string-literal"); + * l_rc = FAPI_ATTR_SET(l_id, l_pTarget, l_pString); + * + * To get a copy of an integer attribute and set the attribute + * uint64_t l_val = 0; + * l_rc = FAPI_ATTR_GET(l_id, l_pTarget, l_val); + * l_rc = FAPI_ATTR_SET(l_id, l_pTarget, l_val); + * + * To get a copy of an integer array attribute and set the attribute + * uint32_t l_pVal[4] = {0}; + * l_rc = FAPI_ATTR_GET(l_id, l_pTarget, l_pVal); + * l_rc = FAPI_ATTR_SET(l_id, l_pTarget, l_pVal); + */ +#define FAPI_ATTR_GET(ID, PTARGET, VAL) \ + fapi::AttributeService::_get(fapi::ID, PTARGET, VAL) +#define FAPI_ATTR_SET(ID, PTARGET, VAL) \ + fapi::AttributeService::_set(fapi::ID, PTARGET, VAL) + +namespace fapi +{ + +/** + * @namespace AttributeService + * + * This class defines the attribute access functions. These functions must not + * be accessed directly, they should only be called by the FAPI_ATTR_GET and + * FAPI_ATTR_SET macros. + * + * Each function comes in two parts. If the caller of FAPI_ATTR_GET attempts to + * get an incorrect type then the normal template function will be instantiated + * and the construction of the undefined InvalidTypeRequestedForAttribute class + * will cause a compile failure. Only if the caller attempts to get the correct + * type will the specialized function be called which will work. + */ +namespace AttributeService +{ + +/** + * @brief Forward declaration of class that will never be defined + */ +class InvalidTypeRequestedForAttribute; + +/** + * @brief Get a copy of a string attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_pValue Reference to pointer that will be set to point to newly + * allocated memory holding the attribute value + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller must free the data with "delete [] o_pValue" + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + char * & o_pValue) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + char * & o_value); + +/** + * @brief Get a copy of a uint8_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_value Reference to data that will be set to the attribute val + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint8_t& o_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint8_t & o_value); + +/** + * @brief Get a copy of a uint32_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_value Reference to data that will be set to the attribute val + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint32_t& o_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint32_t & o_value); + +/** + * @brief Get a copy of a uint64_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_value Reference to data that will be set to the attribute val + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint64_t& o_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint64_t & o_value); + +/** + * @brief Get a copy of a uint8_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_pValues Pointer to data that will be set to the attribute value + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint8_t * const o_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint8_t * const o_pValues); + +/** + * @brief Get a copy of a uint32_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_pValues Pointer to data that will be set to the attribute value + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint32_t * const o_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint32_t * const o_pValues); + +/** + * @brief Get a copy of a uint64_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[out] o_pValues Pointer to data that will be set to the attribute value + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _get(const AttributeId i_id, + const Target * const i_pTarget, + uint64_t * const o_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _get (const AttributeId i_id, + const Target * const i_pTarget, + uint64_t * const o_pValues); + +/** + * @brief Set a string attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[in] i_pValue Pointer to string containing the attribute value to set + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const char * const i_pValue) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const char * const i_pValue); + +/** + * @brief Set a uint8_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[in] i_value Attribute value to set + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint8_t i_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint8_t i_value); + +/** + * @brief Set a uint32_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[in] i_value Attribute value to set + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint32_t i_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint32_t i_value); + +/** + * @brief Set a uint64_t attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated with + * (NULL if system attribute) + * @param[in] i_value Attribute value to set + * + * @return ReturnCode. Zero on success, else error. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint64_t i_value) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint64_t i_value); + +/** + * @brief Set a uint8_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated + * with (NULL if system attribute) + * @param[out] i_pValues Pointer to array containing the attribute values to + * set + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint8_t * const i_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint8_t * const i_pValues); + +/** + * @brief Set a uint32_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated + * with (NULL if system attribute) + * @param[out] i_pValues Pointer to array containing the attribute values to + * set + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint32_t * const i_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint32_t * const i_pValues); + +/** + * @brief Set a uint64_t array attribute + * + * @param[in] i_id Attribute ID + * @param[in] i_pTarget Pointer to Target that the attribute is associated + * with (NULL if system attribute) + * @param[out] i_pValues Pointer to array containing the attribute values to + * set + * + * @return ReturnCode. Zero on success, else error. + * + * @note The caller's o_pValues pointer must point to memory large enough to + * hold the attribute. + */ +template +ReturnCode _set(const AttributeId i_id, + const Target * const i_pTarget, + const uint64_t * const i_pValues) +{ + InvalidTypeRequestedForAttribute(); + return FAPI_RC_SUCCESS; +} +template<> // Specialized template function defined in fapiAttributeService.C +ReturnCode _set (const AttributeId i_id, + const Target * const i_pTarget, + const uint64_t * const i_pValues); + + +} // namespace AttributeService + +} // namespace fapi + +#endif // FAPIATTRIBUTESERVICE_H_ diff --git a/src/include/usr/hwpf/fapi/fapiHwAccess.H b/src/include/usr/hwpf/fapi/fapiHwAccess.H new file mode 100644 index 000000000..948d4feb0 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiHwAccess.H @@ -0,0 +1,115 @@ +/** + * @file fapiHwAccess.H + * + * @brief Defines the hardware access functions that platform code must + * implement. It is a HWP requirement that these be "C" functions. + */ + +#ifndef FAPIHWACCESS_H_ +#define FAPIHWACCESS_H_ + +#include +#include +#include +#include + +namespace fapi +{ + /** + * @brief Enumeration of modify modes used in modify operations + */ + enum ChipOpModifyMode + { + CHIP_OP_MODIFY_MODE_OR = 1, + CHIP_OP_MODIFY_MODE_AND = 2, + CHIP_OP_MODIFY_MODE_XOR = 3, + }; +} + +extern "C" +{ + +//------------------------------------------------------------------------------ +// HW Communication Functions +//------------------------------------------------------------------------------ + +/** + * @brief Reads a SCOM register from a Chip + * @param[in] i_target Target to operate on + * @param[in] i_address Scom address to read from + * @param[out] o_data ecmdDataBufferBase object that holds data read from + * address + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode GetScom(const fapi::Target& i_target, + const uint64_t i_address, + ecmdDataBufferBase & o_data); + +/** + * @brief Writes a SCOM register on a Chip + * @param[in] i_target Target to operate on + * @param[in] i_address Scom address to write to + * @param[in] i_data ecmdDataBufferBase object that holds data to write into + * address + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode PutScom(const fapi::Target& i_target, + const uint64_t i_address, + ecmdDataBufferBase & i_data); + +/** + * @brief Writes a SCOM register under mask to a chip + * @param[in] i_target Target to operate on + * @param[in] i_address Scom address to write to + * @param[in] i_data ecmdDataBufferBase object that holds the data + * @param[in] i_mask ecmdDataBufferBase object that holds the mask (i_data to + * write) + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode PutScomUnderMask(const fapi::Target& i_target, + const uint64_t i_address, + ecmdDataBufferBase & i_data, + ecmdDataBufferBase & i_mask); + + +/** + * @brief Reads a CFAM register from a chip + * @param[in] i_target Target to operate on + * @param[in] i_address CFAM address to read from + * @param[out] o_data ecmdDataBufferBase object that holds data read from + * address + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode GetCfamRegister(const fapi::Target& i_target, + const uint32_t i_address, + ecmdDataBufferBase & o_data); + +/** + * @brief Writes a CFAM register to a chip + * @param[in] i_target Target to operate on + * @param[in] i_address CFAM address to write to + * @param[in] i_data ecmdDataBufferBase object that holds data to write into + * address + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode PutCfamRegister(const fapi::Target& i_target, + const uint32_t i_address, + ecmdDataBufferBase & i_data); + +/** + * @brief Read-modify-write a CFAM register on a chip + * @param[in] i_target Target to operate on + * @param[in] i_address CFAM address to write to + * @param[in] i_data ecmdDataBufferBase object that holds the modifying data + * @param[in] i_modifyMode The modify mode (or/and/xor) + * @return ReturnCode. Zero on success, else platform specified error + */ +fapi::ReturnCode ModifyCfamRegister(const fapi::Target& i_target, + const uint32_t i_address, + ecmdDataBufferBase & i_data, + const fapi::ChipOpModifyMode i_modifyMode); + + +} // extern "C" + +#endif // FAPIHWACCESS_H_ diff --git a/src/include/usr/hwpf/fapi/fapiReturnCode.H b/src/include/usr/hwpf/fapi/fapiReturnCode.H new file mode 100644 index 000000000..29b448add --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiReturnCode.H @@ -0,0 +1,174 @@ +/** + * @file fapiReturnCode.H + * + * @brief Defines the ReturnCode class that is a generic return code. + */ + +#ifndef FAPIRETURNCODE_H_ +#define FAPIRETURNCODE_H_ + +#include +#include +#include + +namespace fapi +{ + +// Forward declaration +class ReturnCodeDataRef; + +/** + * @class ReturnCode + * + * This class provides a generic return code. It contains the rcValue (return + * code value) which is of type uint32_t. A user can treat a ReturnCode just + * as if it were a uint32_t. + * + * FAPI, PLAT and HWP code can all create a ReturnCode. PLAT can optionally add + * platform specific ReturnCodeData to it. + * + * A ReturnCode is copyable and assignable. Therefore, it cannot be subclassed. + * + * When a ReturnCode is copied, any ReturnCodeData is not copied because it may + * be heavyweight. Both ReturnCodes will refer to the same ReturnCodeData. + * ReturnCodeData is only deleted when the last ReturnCode with a reference to + * it is deleted. It is possible for PLAT to get a pointer to the ReturnCodeData + * and to optionally release the data (ReturnCode no longer responsible for + * deleting). This is done using the intermediate ReturnCodeDataRef class. + * + * A ReturnCode object is not thread safe, multiple threads must not use the + * same ReturnCode object concurrently. + */ +class ReturnCode +{ +public: + + /** + * @brief Enumeration of return code creators + */ + enum returnCodeCreator + { + CREATOR_FAPI = 1, + CREATOR_PLAT = 2, + CREATOR_HWP = 3, + }; + + /** + * @brief Default constructor. Sets rcValue to success + */ + ReturnCode(); + + /** + * @brief Constructor. Sets rcValue to the specified value + * + * @note This allows an implicit conversion between a uint32_t and a + * ReturnCode. A user is allowed to return a uint32_t from a function + * that returns a ReturnCode or is allowed to pass a uint32_t to a + * function that expects a ReturnCode and in both cases, the uint32_t + * will be automatically converted to a ReturnCode. + * + * @param[in] i_rcValue The rcValue to set + */ + ReturnCode(const uint32_t i_rcValue); + + /** + * @brief Copy Constructor + * + * @param[in] i_right Reference to ReturnCode to copy + */ + ReturnCode(const ReturnCode & i_right); + + /** + * @brief Destructor + */ + ~ReturnCode(); + + /** + * @brief Assignment Operator. + * + * @param[in] i_right Reference to ReturnCode to assign from. + * + * @return Reference to 'this' ReturnCode + */ + ReturnCode & operator=(const ReturnCode & i_right); + + /** + * @brief Assignment Operator. + * + * @param[in] i_rc Reference to rcValue to assign + * + * @return Reference to 'this' ReturnCode + */ + ReturnCode & operator=(const uint32_t i_rcValue); + + /** + * @brief Returns if the return code indicates success + * + * @return bool. True if ok, else false + */ + bool ok() const; + + /** + * @brief uint32_t conversion function. Returns the rcValue + * + * @note This allows a user to directly compare: + * 1/ ReturnCode to uint32_t (ReturnCode converted to uint32_t) + * 2/ ReturnCode to ReturnCode (Both ReturnCode converted to uint32_t) + */ + operator uint32_t() const; + + /** + * @brief Get a pointer to any ReturnCodeData. ReturnCode is still + * responsible for deletion of the data. The caller must not delete + * + * The data pointed to is only meaningful to platform code. + * + * @return void *. Pointer to any ReturnCodeData. If NULL then no data + */ + void * getData() const; + + /** + * @brief Get a pointer to any ReturnCodeData and release ownership from + * ReturnCode. The caller is responsible for deletion. + * + * The data pointed to is only meaningful to platform code. + * + * @return void *. Pointer to any ReturnCodeData. If NULL then no data + */ + void * releaseData(); + + /** + * @brief Sets ReturnCodeData. The ReturnCode object takes responsibility + * for deleting the data (platform code actually implements the + * delete function and must know the type and how to delete it). + * + * The data pointed to is only meaningful to platform code. + * + * param[in] i_pData Pointer to ReturnCodeData (on the heap) + */ + void setData(const void * i_pData); + + /** + * @brief Gets the creator of the return code + * + * @return ReturnCodeCreator + */ + returnCodeCreator getCreator() const; + +private: + + /** + * @brief Removes interest in pointed to ReturnCodeDataRef + */ + void removeData(); + + // The rcValue + uint32_t iv_rcValue; + + // Pointer to ReturnCodeDataRef + ReturnCodeDataRef * iv_pDataRef; +}; + +} + +#endif // FAPIRETURNCODE_H_ diff --git a/src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H b/src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H new file mode 100644 index 000000000..683438add --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H @@ -0,0 +1,106 @@ +/** + * @file fapiReturnCodeDataRef.H + * + * @brief Defines the ReturnCodeDataRef class that provides a pointer and a + * reference count to a platform specific ReturnCodeData object. + */ + +#ifndef FAPIRETURNCODEDATAREF_H_ +#define FAPIRETURNCODEDATAREF_H_ + +#include +#include + +namespace fapi +{ + +/** + * @class ReturnCodeDataRef + * + * This class contains a pointer to platform specific ReturnCodeData and a + * reference count recording how many ReturnCodes have a pointer to itself. + * + * It is used exclusively by the ReturnCode class. Multiple copies of a + * ReturnCode will all point to the same ReturnCodeDataRef. The ReturnCodes + * maintain the reference count, the last ReturnCode to remove its reference + * will delete the ReturnCodeDataRef which in turn deletes the ReturnCodeData. + * The ReturnCodeData pointer is maintained in this class so that releasing the + * data releases it from all ReturnCode copies. + * + * A ReturnCodeDataRef object is not thread safe, multiple threads must not use + * the same ReturnCodeDataRef object concurrently. + */ +class ReturnCodeDataRef +{ +public: + + /** + * @brief Constructor + * + * @param[in] i_pData Pointer to platform specific ReturnCodeData + */ + explicit ReturnCodeDataRef(const void * i_pData); + + /** + * @brief Destructor + */ + ~ReturnCodeDataRef(); + + /** + * @brief Increments the ref count + */ + void incRefCount(); + + /** + * @brief Decrements the ref count + * + * @return bool True if zero reached + */ + bool decRefCountCheckZero(); + + /** + * @brief Get a pointer to ReturnCodeData. ReturnCodeDataRef is still + * responsible for deletion of the data. The caller must not delete + * + * The pointer is only meaningful to platform code. + * + * @return void *. Pointer to ReturnCodeData. If NULL then no data (must + * have been released) + */ + const void * getData() const; + + /** + * @brief Get a pointer to any ReturnCodeData and release ownership from + * ReturnCodeDataRef. The caller is responsible for deletion. + * + * The pointer is only meaningful to platform code. + * + * @return void *. Pointer to ReturnCodeData. If NULL then no data (must + * have been released) + */ + const void * releaseData(); + +private: + + // Copy constructor and assignment operator disabled + ReturnCodeDataRef(const ReturnCodeDataRef & i_right); + ReturnCodeDataRef & operator=(const ReturnCodeDataRef & i_right); + + /** + * @brief Deletes the ReturnCodeData + * + * @note Implemented by platform code because only platform code knows the + * type of the data and how to delete it. + */ + void deleteData(); + + // The reference count (how many ReturnCodes are pointing to this object) + uint32_t iv_refCount; + + // Pointer to platform specific ReturnCodeData + const void * iv_pData; +}; + +} + +#endif // FAPIRETURNCODEDATAREF_H_ diff --git a/src/include/usr/hwpf/fapi/fapiReturnCodes.H b/src/include/usr/hwpf/fapi/fapiReturnCodes.H new file mode 100644 index 000000000..4d3cc7db2 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiReturnCodes.H @@ -0,0 +1,39 @@ +/** + * @file fapiReturnCodes.H + * + * @brief Defines the returns codes generated by HWPF code. + */ + +#ifndef FAPIRETURNCODES_H_ +#define FAPIRETURNCODES_H_ + +#include + +namespace fapi +{ + +/** + * @brief Enumeration of return codes + */ +enum +{ + FAPI_RC_SUCCESS = 0, + + // Flag bits indicating which code generated the error If no flag set then + // it is generated by HWP + FAPI_RC_FAPI_MASK = 0x04000000, // FAPI generated error + FAPI_RC_PLAT_MASK = 0x02000000, // PLAT generated error + FAPI_RC_ECMD_MASK = ECMD_ERR_ECMD, // ECMD generated error (0x01000000) + + // FAPI generated return codes + FAPI_RC_NOT_IMPLEMENTED = FAPI_RC_FAPI_MASK | 0x01, + + // PLAT generated return codes + FAPI_RC_PLAT_ERR_SEE_DATA = FAPI_RC_PLAT_MASK | 0x01, + // Error details in attached ReturnCodeData + FAPI_RC_PLAT_NOT_IMPLEMENTED = FAPI_RC_PLAT_MASK | 0x02, +}; + +} + +#endif // FAPIRETURNCODES_H_ diff --git a/src/include/usr/hwpf/fapi/fapiSystemConfig.H b/src/include/usr/hwpf/fapi/fapiSystemConfig.H new file mode 100644 index 000000000..29eca2cc4 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiSystemConfig.H @@ -0,0 +1,73 @@ +/** + * @file fapiSystemConfig.H + * + * @brief Defines the System Config query functions that platform code must + * implement. It is an eCMD requirement that these be "C" functions. + */ + +#ifndef FAPISYSTEMCONFIG_H_ +#define FAPISYSTEMCONFIG_H_ + +#include +#include +#include +#include + +extern "C" +{ + +/** + * @brief Gets the functional chiplets that are children of the supplied target + * + * @param[in] i_target Parent target + * @param[in] i_targetType Type of chiplet required + * @param[out] o_chiplets Reference to vector that is filled in with the + * result chiplets + * + * @return ReturnCode. Zero on success, else error + */ +fapi::ReturnCode GetFunctionalChiplets(const fapi::Target& i_target, + const fapi::TargetType i_chipletType, + std::vector & o_chiplets); + +/** + * @brief Gets the existing chiplets that are children of the supplied target + * + * @param[in] i_target Parent target + * @param[in] i_targetType Type of chiplet required + * @param[out] o_chiplets Reference to vector that is filled in with the + * result chiplets + * + * @return ReturnCode. Zero on success, else error + */ +fapi::ReturnCode GetExistingChiplets(const fapi::Target& i_target, + const fapi::TargetType i_chipletType, + std::vector & o_chiplets); + +/** + * @brief Gets the functional DIMMs that are children of the supplied target + * + * @param[in] i_target Parent target + * @param[out] o_dimms Reference to vector that is filled in with the result + * DIMMs + * + * @return ReturnCode. Zero on success, else error + */ +fapi::ReturnCode GetFunctionalDimms(const fapi::Target& i_target, + std::vector & o_dimms); + +/** + * @brief Gets the existing DIMMs that are children of the supplied target + * + * @param[in] i_target Parent target + * @param[out] o_dimms Reference to vector that is filled in with the result + * DIMMs + * + * @return ReturnCode. Zero on success, else error + */ +fapi::ReturnCode GetExistingDimms(const fapi::Target& i_target, + std::vector & o_dimms); + +} // extern "C" + +#endif // FAPISYSTEMCONFIG_H_ diff --git a/src/include/usr/hwpf/fapi/fapiTarget.H b/src/include/usr/hwpf/fapi/fapiTarget.H new file mode 100644 index 000000000..af22137b9 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiTarget.H @@ -0,0 +1,195 @@ +/** + * @file fapiTarget.H + * + * @brief Defines the Target class that is a generic target of a Hardware + * Procedure operation. + */ + +#ifndef FAPITARGET_H_ +#define FAPITARGET_H_ + +#include +#include + +namespace fapi +{ + +/** + * @brief Enumeration of target types values (bitmask values) + */ +enum TargetType +{ + TARGET_TYPE_NONE = 0x00000000, + TARGET_TYPE_SYSTEM = 0x00000001, + TARGET_TYPE_DIMM = 0x00000002, + TARGET_TYPE_PROC_CHIP = 0x00000004, + TARGET_TYPE_MEMBUF_CHIP = 0x00000008, + TARGET_TYPE_EX_CHIPLET = 0x00000010, + TARGET_TYPE_MBA_CHIPLET = 0x00000020, + TARGET_TYPE_MBS_CHIPLET = 0x80000040, + TARGET_TYPE_MCS_CHIPLET = 0x80000080, +}; + +/** + * @brief Typedef used when passing multiple TargetType values + */ +typedef uint32_t TargetTypes_t; + +/** + * @class Target + * + * This class provides a generic Target of a Hardware Procedure Operation. + * + * A Target contains a void * pointer to a handle which is only meaningful to + * platform code. + * + * A Target object is copyable and assignable. Therefore, it cannot be + * subclassed. + * + * A Target object is not thread safe, multiple threads must not use the same + * Target object concurrently. + */ +class Target +{ +public: + + /** + * @brief Default constructor + */ + Target(); + + /** + * @brief Constructor + * + * @param[in] i_type Target type + * @param[in] i_pHandle Pointer to platform specific Target handle + */ + Target(const TargetType i_type, + const void * i_pHandle); + + /** + * @brief Copy Constructor + * + * @param[in] i_right Reference to Target to copy + */ + Target(const Target & i_right); + + /** + * @brief Destructor + */ + ~Target(); + + /** + * @brief Assignment Operator. + * + * @param[in] i_right Reference to Target to assign from. + * + * @return Reference to 'this' Target + */ + Target & operator=(const Target & i_right); + + /** + * @brief Equality Comparison Operator + * + * @param[in] i_right Reference to Target to compare. + * + * @return bool. True if equal. + */ + bool operator==(const Target & i_right) const; + + /** + * @brief Inequality Comparison Operator + * + * @param[in] i_right Reference to Target to compare. + * + * @return bool. True if not equal. + */ + bool operator!=(const Target & i_right) const; + + /** + * @brief Get the handle pointer. + * + * The handle is only meaningful to platform code. + * + * @return Handle_t. The handle. + */ + void * get() const; + + /** + * @brief Set the handle. Platform using Handle_t as handle + * + * The handle is only meaningful to platform code. + * + * @param[in] i_pHandle Pointer to platform specific handle + */ + void set(const void * i_pHandle); + + /** + * @brief Get the target type + * + * @return The type of target represented by this target + */ + TargetType getType() const; + + /** + * @brief Set the target type + * + * @param[in] i_type The type of target represented by this target + */ + void setType(const TargetType i_type); + + /** + * @brief Convert a target to an ecmd-format target string + * + * @note Implemented by platform code + * + * @return A pointer to a c-string. If the object cannot be converted to a + * valid ecmd string, a NULL pointer is returned. + * + * IMPORTANT: It is the caller's responsibility to free the returned string + * when done with it by calling "free(char*)". + */ + const char * toString() const; + +private: + + /** + * @brief Compare the handle + * + * @note Implemented by platform code because only platform code knows the + * type pointed to by iv_pHandle to compare + * + * @param[in] i_right Reference to Target to compare handle to + * + * @return bool. True if the same + */ + bool compareHandle(const Target & i_right) const; + + /** + * @brief Copy the handle + * + * @note Implemented by platform code because only platform code knows the + * type pointed to by iv_pHandle to copy + * + * @param[in] i_right Reference to Target to copy handle from + */ + void copyHandle(const Target & i_right); + + /** + * @brief Delete the handle + * + * @note Implemented by platform code because only platform code knows the + * type to delete and if it should actually be deleted + */ + void deleteHandle(); + + // Type of target + TargetType iv_type; + + // Pointer to platform specific Target Handle + const void * iv_pHandle; +}; + +} + +#endif // FAPITARGET_H_ diff --git a/src/include/usr/hwpf/fapi/fapiUtil.H b/src/include/usr/hwpf/fapi/fapiUtil.H new file mode 100644 index 000000000..291410454 --- /dev/null +++ b/src/include/usr/hwpf/fapi/fapiUtil.H @@ -0,0 +1,28 @@ +/** + * @file fapiUtil.H + * + * @brief Defines utility functions that the platform code must implement. + */ + +#ifndef FAPIUTIL_H_ +#define FAPIUTIL_H_ + +#include +#include +#include + + +namespace fapi +{ +/** + * @brief Assert that an expression is true. Aborting the process if false. + * + * @note Implemented by platform code + * + * @param[in] i_expression If not true then process should be aborted + */ +void fapiAssert(bool i_expression); + +} + +#endif // FAPIUTIL_H_ -- cgit v1.2.1