diff options
author | Thi Tran <thi@us.ibm.com> | 2011-06-28 11:17:12 -0500 |
---|---|---|
committer | Thi N. Tran <thi@us.ibm.com> | 2011-06-30 08:19:52 -0500 |
commit | e93bda2d2a30ff9959384dce0563ab143bc30aad (patch) | |
tree | dea7e740ae61ae2fe343823ad31654fbce6992bf /src/include/usr | |
parent | a4809cd65ce96d0b56ec316b14836087cf1d647b (diff) | |
download | talos-hostboot-e93bda2d2a30ff9959384dce0563ab143bc30aad.tar.gz talos-hostboot-e93bda2d2a30ff9959384dce0563ab143bc30aad.zip |
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 <iawillia@us.ibm.com>
Diffstat (limited to 'src/include/usr')
-rw-r--r-- | src/include/usr/ecmddatabuffer/ecmdDataBuffer.H | 120 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapi.H | 22 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiAttributeService.H | 426 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiHwAccess.H | 115 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiReturnCode.H | 174 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiReturnCodeDataRef.H | 106 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiReturnCodes.H | 39 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiSystemConfig.H | 73 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiTarget.H | 195 | ||||
-rw-r--r-- | src/include/usr/hwpf/fapi/fapiUtil.H | 28 | ||||
-rw-r--r-- | src/include/usr/hwpf/hwp/fapiTestHwp.H | 31 | ||||
-rw-r--r-- | src/include/usr/hwpf/plat/fapiPlatHwpExecutor.H | 22 | ||||
-rw-r--r-- | src/include/usr/hwpf/plat/fapiPlatHwpInvoker.H | 32 | ||||
-rw-r--r-- | src/include/usr/hwpf/plat/fapiPlatTrace.H | 46 |
14 files changed, 1429 insertions, 0 deletions
diff --git a/src/include/usr/ecmddatabuffer/ecmdDataBuffer.H b/src/include/usr/ecmddatabuffer/ecmdDataBuffer.H new file mode 100644 index 000000000..afb438431 --- /dev/null +++ b/src/include/usr/ecmddatabuffer/ecmdDataBuffer.H @@ -0,0 +1,120 @@ +#ifndef ECMDDATABUFFER_H +#define ECMDDATABUFFER_H + +/** + * @file ecmdDataBuffer.H + * @brief Provides a means to handle data from the eCMD C API + * + * @todo - This is only created to compile code. Needs to be replaced with John Farrugia's version + * + */ + +//---------------------------------------------------------------------- +// Constants +//---------------------------------------------------------------------- +/* Define these if for some reason we are building without ecmdReturnCodes.H */ +#define ECMD_ERR_ECMD 0x01000000 ///< Error came from eCMD +#define ECMD_DBUF_SUCCESS 0x0 ///< DataBuffer returned successfully + +/** + @brief Provides a means to handle data from the eCMD C API +*/ +class ecmdDataBufferBase { + +public: + + /** @name ecmdDataBufferBase Constructors */ + /** + * @brief Default Constructor + * @post buffer is not allocated, can be allocated later with setWordLength, setCapacity or setBitLength + */ + ecmdDataBufferBase(); + + /** + * @brief Constructor + * @param i_numBits Size of data in bits to initialize + * @post ecmdDataBufferBase is initialized and zero'd out + */ + explicit ecmdDataBufferBase(uint32_t i_numBits); + + /** + * @brief Default Destructor + */ + virtual ~ecmdDataBufferBase(); + + /** + * @brief Called by the destructor, available to user to reset buffer to default constructor state + * @retval ECMD_DBUF_SUCCESS on success + * @retval ECMD_DBUF_NOT_OWNER when called on buffer not owned + * @retval nonzero on failure + * @post Memory deallocated and size set to 0 + */ + uint32_t clear(); + + /** + * @brief Reinitialize the Buffer to specified length + * @param i_newNumBits Length of new buffer in bits + * @retval ECMD_DBUF_SUCCESS on success + * @retval ECMD_DBUF_INIT_FAIL failure occurred setting new length + * @retval ECMD_DBUF_NOT_OWNER when called on buffer not owned + * @post Buffer is reinitialized and zero'd out + * + * NOTE : Capacity will be adjusted to fit new size if neccesary + * CAUTION : All data stored in buffer will be lost + */ + uint32_t setBitLength(uint32_t i_newNumBits); + + /** + * @brief Reinitialize the internal buffer to specified length + * @param i_newNumWords length of internal data buffer in words + * @retval ECMD_DBUF_SUCCESS on success + * @retval ECMD_DBUF_INIT_FAIL failure occurred setting new length + * @retval ECMD_DBUF_NOT_OWNER when called on buffer not owned + * @post Internal buffer is reinitialized and zero'd out. Requests to decrease the capacity are ignored + * + * CAUTION : All data stored in buffer will be lost + */ + uint32_t setCapacity (uint32_t i_newNumWords); + + + /** + * @brief Set a doubleword of data in buffer + * @param i_doublewordoffset Offset of doubleword to set + * @param i_value 64 bits of data to put into doubleword + * @retval ECMD_DBUF_SUCCESS on success + * @retval ECMD_DBUF_BUFFER_OVERFLOW i_doublewordoffset is not contained in the size of this buffer + * + * NOTE : If the buffer length != double word boundary, when setting the last double word + * data in i_value past the buffer length is cleared before being stored in the buffer + */ + uint32_t setDoubleWord(uint32_t i_doublewordoffset, uint64_t i_value); + + /** + * @brief Fetch a doubleword from ecmdDataBuffer + * @param i_doublewordoffset Offset of doubleword to fetch + * @retval Value of doubleword requested + */ + uint64_t getDoubleWord(uint32_t i_doublewordoffset) const; + + /** + * @brief Return the length of the buffer in words + * @retval Buffer length in words rounded up + */ + uint32_t getWordLength() const; + + /** + * @brief Clear entire buffer to 0's + * @retval ECMD_DBUF_SUCCESS on success + */ + uint32_t flushTo0(); + +protected: + uint32_t iv_Capacity; ///< Actual buffer capacity - always >= getNumWords() + uint32_t iv_NumBits; ///< Specified buffer size in bits + uint32_t *iv_Data; ///< Pointer to buffer inside iv_RealData + uint32_t *iv_RealData; ///< Real buffer - with header and tail + uint32_t iv_LocalData[4]; ///< If the buffer is <= 64 bits, we'll store the data locally in the class + bool iv_UserOwned; ///< Whether or not this buffer owns the data +}; + +#endif /* ECMDDATABUFFER_H */ 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 <fapiTarget.H> +#include <fapiReturnCode.H> +#include <fapiUtil.H> +#include <fapiHwAccess.H> +#include <fapiSystemConfig.H> +#include <fapiPlatTrace.H> +#include <fapiPlatHwpExecutor.H> +#include <fapiAttributeService.H> +#include <fapiHwpReturnCodes.H> // Generated file +#include <fapiAttributeIds.H> // Generated file +#include <ecmdDataBuffer.H> + +#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 <stdint.h> +#include <fapiAttributeIds.H> +#include <fapiReturnCode.H> +#include <fapiTarget.H> + +/** + * @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##_Type>(fapi::ID, PTARGET, VAL) +#define FAPI_ATTR_SET(ID, PTARGET, VAL) \ + fapi::AttributeService::_set<fapi::ID##_Type>(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<typename T> +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<char *> (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<typename T> +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<uint8_t> (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<typename T> +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<uint32_t> (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<typename T> +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<uint64_t> (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<typename T> +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<uint8_t *> (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<typename T> +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<uint32_t *> (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<typename T> +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<uint64_t *> (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<typename T> +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<char *> (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<typename T> +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<uint8_t> (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<typename T> +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<uint32_t> (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<typename T> +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<uint64_t> (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<typename T> +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<uint8_t *> (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<typename T> +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<uint32_t *> (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<typename T> +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<uint64_t *> (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 <stdint.h> +#include <fapiReturnCode.H> +#include <fapiTarget.H> +#include <ecmdDataBuffer.H> + +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 <stdint.h> +#include <stddef.h> +#include <fapiReturnCodes.H> + +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 <stdint.h> +#include <stddef.h> + +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 <ecmdDataBuffer.H> + +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 <stdint.h> +#include <vector> +#include <fapiReturnCode.H> +#include <fapiTarget.H> + +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<fapi::Target> & 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<fapi::Target> & 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<fapi::Target> & 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<fapi::Target> & 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 <stdint.h> +#include <stddef.h> + +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 <stdint.h> +#include <stddef.h> +#include <fapi.H> + + +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_ diff --git a/src/include/usr/hwpf/hwp/fapiTestHwp.H b/src/include/usr/hwpf/hwp/fapiTestHwp.H new file mode 100644 index 000000000..db619737f --- /dev/null +++ b/src/include/usr/hwpf/hwp/fapiTestHwp.H @@ -0,0 +1,31 @@ +/** + * @file fapiTestHwp.H + * + * @brief Defines test Hardware Procedures that are intended to test out the + * Hardware Procedure Framework + */ + +#ifndef FAPITESTHWPROC_H_ +#define FAPITESTHWPROC_H_ + +#include <fapi.H> + +// HWPs are defined as C functions because platforms may wish to package them +// in linux shared libraries which are DL-Opened +extern "C" +{ + +/** + * @brief Finds if a P7 EM0 chiplet clock is on + * + * @param[in] i_chip Target chip + * @param[out] o_clocksOn True if clocks are on, else false + * + * @return ReturnCode + */ +fapi::ReturnCode hwpIsP7EM0ChipletClockOn(const fapi::Target & i_chip, + bool & o_clocksOn); + +} // extern "C" + +#endif // FAPITESTHWPROC_H_ diff --git a/src/include/usr/hwpf/plat/fapiPlatHwpExecutor.H b/src/include/usr/hwpf/plat/fapiPlatHwpExecutor.H new file mode 100644 index 000000000..c2b7e5e10 --- /dev/null +++ b/src/include/usr/hwpf/plat/fapiPlatHwpExecutor.H @@ -0,0 +1,22 @@ +/** + * @file fapiPlatHwpExecutor.H + * + * @brief Defines the FAPI HWP Executor Macro. + * + * The HWP Executor macro is called when a PLAT invoker function or a HWP wants + * to execute a HWP. Each platform can modify the macro to do any platform + * specific work to execute the HWP (e.g. dlopening a shared library) + */ + +#ifndef FAPIPLATHWPEXECUTOR_H_ +#define FAPIPLATHWPEXECUTOR_H_ + +/** + * @brief HWP Executor macro + * + * By default, this macro just calls the HWP directly. If this cannot be done + * then the platform needs to modify + */ +#define FAPI_EXEC_HWP(RC, FUNC, _args_...) RC = FUNC(_args_) + +#endif // FAPIPLATHWPEXECUTOR_H_ diff --git a/src/include/usr/hwpf/plat/fapiPlatHwpInvoker.H b/src/include/usr/hwpf/plat/fapiPlatHwpInvoker.H new file mode 100644 index 000000000..232cb981c --- /dev/null +++ b/src/include/usr/hwpf/plat/fapiPlatHwpInvoker.H @@ -0,0 +1,32 @@ +/** + * @file fapiPlatHwpInvoker.H + * + * @brief Defines the platform specific HW Procedure invoker functions. + * + * Note that each platform needs to provide an invoker function for each HW + * procedure. Prototypes cannot be provided because each platform will have + * functions that take platform specific targets and return platform specific + * return codes. + */ + +#ifndef FAPIPLATHWPINVOKER_H_ +#define FAPIPLATHWPINVOKER_H_ + +#include <targeting/targetservice.H> +#include <errl/errlentry.H> + +namespace fapi +{ + +/** + * @brief Invokes hwpIsP7EM0ChipletClockOn procedure + * + * @param[in] i_target Pointer to Chip + * @param[out] o_clocksOn True if EM0 clocks are on, else false + */ +errlHndl_t invokeHwpIsP7EM0ChipletClockOn(TARGETING::Target* i_target, + bool & o_clocksOn); + +} + +#endif // FAPIPLATHWPINVOKER_H_ diff --git a/src/include/usr/hwpf/plat/fapiPlatTrace.H b/src/include/usr/hwpf/plat/fapiPlatTrace.H new file mode 100644 index 000000000..e02bd481a --- /dev/null +++ b/src/include/usr/hwpf/plat/fapiPlatTrace.H @@ -0,0 +1,46 @@ +/** + * @file platTrace.H + * + * @brief Defines the FAPI trace macros. + * + * Note that platform code must provide the implementation. + * + * FAPI has provided a default implementation of printfs. Platform code must + * provide an alternate implementation if needed. + */ + +#ifndef PLATTRACE_H_ +#define PLATTRACE_H_ + +#include <stdio.h> +#include <trace/interface.H> + +//****************************************************************************** +// Trace buffer names +//****************************************************************************** +const char * const FAPI_INF_TRACE_NAME = "FAPI_T"; +const char * const FAPI_IMP_TRACE_NAME = "FAPI_I"; +const char * const FAPI_ERR_TRACE_NAME = "FAPI_E"; +const char * const FAPI_DBG_TRACE_NAME = "FAPI_D"; + +//****************************************************************************** +// Trace descriptors that are defined in a C file +//****************************************************************************** +extern trace_desc_t* g_fapiInfTd; +extern trace_desc_t* g_fapiImpTd; +extern trace_desc_t* g_fapiErrTd; +extern trace_desc_t* g_fapiDbgTd; + +// Information traces (standard flight recorder that can wrap often) +#define FAPI_INF(_fmt_, _args_...) TRACFCOMP(g_fapiInfTd, _fmt_, ##_args_ ) + +// Important traces (should not wrap often) +#define FAPI_IMP(_fmt_, _args_...) TRACFCOMP(g_fapiImpTd, _fmt_, ##_args_ ) + +// Error traces (should not wrap often) +#define FAPI_ERR(_fmt_, _args_...) TRACFCOMP(g_fapiErrTd, _fmt_, ##_args_ ) + +// Debug traces (can wrap often) +#define FAPI_DBG(_fmt_, _args_...) TRACDCOMP(g_fapiDbgTd, _fmt_, ##_args_) + +#endif // PLATTRACE_H_ |